Troubleshooting
Error codes for credential reads, what each means and how to fix it, and the common problems with PAM entries, runners, DAST, API and host scans.
Troubleshooting
Start on the runner machine:
safeguard vault providers # is the provider file accepted, is each provider complete?
safeguard secrets test <reference> # can this machine read it? prints the code and reason
tail -n 20 ~/.safeguard/vault-audit.jsonl # what the last reads didEvery failure message has the same shape: what could not be read, from which provider, why, and the next step. For example:
Could not read the credential for the DAST login password from CyberArk (cyberark-ccp): the AppID is not allowed to read this object. Check the AppID's permission on the Safe.Error codes
| Code | Meaning | What to do |
|---|---|---|
NOT_CONFIGURED | The runner has no provider for this reference, or its settings are incomplete or refused: missing url, an env:// variable that is not set, a key file that cannot be read, a plain http:// url, an inline secret. | safeguard vault providers names the problem. Check the provider name in the reference matches the file. |
AUTH_FAILED | The PAM did not accept the runner's own sign-in: client certificate, API user and key, token, AppRole, Kubernetes role. | Check the identity in the provider file and that it is enabled in the PAM. For ARCON, check the variant and the sign-in body format. |
FORBIDDEN | The runner signed in, but its identity may not read this object, or an approval is pending. | Grant the identity read on this account, Safe, path or variable. Remove the approval step for this identity. |
NOT_FOUND | The PAM has no such object. | Check every part of the reference: for ARCON target type, server and user exactly as registered; for CCP Safe, Object, folder; for Vault mount, path and data/. |
TLS | The PAM's certificate is not trusted, or the client certificate was refused during the handshake. | Set ca_cert to the CA that issued the PAM's certificate. Check client_cert and client_key match. |
UNREACHABLE | No connection, or the PAM answered with a server error or a rate limit, after the retries. | Check DNS, firewall and proxy from the runner (curl -v https://<pam>/). Put the PAM host in NO_PROXY. |
TIMEOUT | The PAM did not answer within timeout (default 15 s), after the retries. | Raise timeout, check the PAM's health. |
BAD_REFERENCE | The reference is malformed, or names a field the provider does not have. | Compare with the reference format on the provider's page. |
DISABLED | env:// or file:// references are turned off here (always on Safeguard's cloud scanner). | Use a vault or PAM reference, or set allow_env / allow_file on the runner. |
EMPTY | The PAM answered without a value, or with an error the runner could not classify. The PAM's own message is shown when there is one. | Check password_json_path against the PAM's answer, and that the account has a password. |
NOT_ALLOWED | The runner's provider file does not allow this reference (allowed_refs). No request was sent to the PAM. | Add a matching pattern to allowed_refs if the read is intended. |
Codes for credentials in the Safeguard vault
These come from the Safeguard vault when a scan or a person uses a credential that has a policy. They appear in the scan's error, in the app, and in the audit log.
| Code | Meaning | What to do |
|---|---|---|
NOT_PERMITTED | The person or runner that signed in does not hold USE on this credential. | Ask someone with MANAGE to add a grant in the credential's Access tab. Check the runner is signed in as the user who holds it. |
NOT_BOUND | The scan's target, scan type or runner is outside the credential's bindings. | Check the Bindings tab. Add the target pattern, scan type or runner, or use another credential. |
RUNNER_NOT_ALLOWED | The credential is bound to named runners and this runner is not one of them. | Add the runner to the bindings, or run the scan on a listed runner. |
APPROVAL_PENDING | The credential needs an approval and nobody has decided yet. The message has the request id. | Ask an approver to decide in Access and approvals or with safeguard vault requests approve <number>, then run the scan again. To wait longer, raise native.approval_wait in the provider file. |
APPROVAL_DENIED | An approver denied the request. | Read the comment on the request. Ask again with a reason if the use is right. |
SCAN_CONTEXT_REQUIRED | An approval request named neither a runner nor a scan. | Ask for access from a scan or a runner, so the approver can see what it is for. |
USER_CONTEXT_REQUIRED | A service tried to check a credential out with no signed-in person behind it, for example a scheduled scan. | Start the scan yourself, or use a credential without a policy for scheduled scans. |
ROTATION_HOST_NOT_BOUND | A rotation names a host or URL that the credential's Targets bindings do not cover. | Add the host or URL to the bindings, or change the rotation settings. |
SELF_APPROVAL | You tried to approve your own request. | Ask another approver. |
LEASE_HELD | The credential is set to One user at a time and another scan holds it. | Wait until that scan ends, or ask someone with MANAGE to revoke the lease in the Leases tab. Turn off the setting if parallel scans are fine. |
CHECKOUT_REQUIRED | The credential has a policy and the runner or CLI asked to read it the old way. | Update the CLI on that machine with safeguard self-update and restart the runner. |
WRITE_ONLY | You asked to see a value the policy keeps write-only. | Add a new version instead. To read it, someone with MANAGE must grant REVEAL, and you may need to sign in again. |
FRESH_AUTH_REQUIRED | The action needs a recent sign-in and yours is older. | Sign out, sign in again and repeat. The app does this for you when it can. |
AGENT_CANNOT_MANAGE | An AI agent tried to manage, approve or reveal a credential. | Agents can only use credentials they are granted. Do the action as a person. |
CREDENTIAL_NOT_BOUND | A target form was saved with a credential that is bound to other targets or scan types. | Pick a credential whose bindings include this target, or add the target to its bindings. |
CREDENTIAL_NOT_FOUND | A source-code integration token names a credential that does not exist or that you cannot see. | Pick the credential again. |
PAM_NOT_SUPPORTED_FOR_SCM | A source-code integration was saved with a credential that points at your PAM. | Source-code integrations take a credential stored in the Safeguard vault. Store the token in the vault, or scan from the CLI or a runner with --git-token <reference>. |
VAULT_UNAVAILABLE | Safeguard could not reach the vault when saving a source-code integration. | Try again. If it persists, contact Safeguard support. |
A rotation that fails reports its own codes (VERIFY_FAILED, HOST_KEY_MISMATCH, ROLLBACK_FAILED and others). See Rotation.
Common problems
"From your PAM vault" is not offered when adding an entry. PAM entries are not turned on for your organization. Contact Safeguard support.
There is no Credentials Vault page, or no Providers tab or "Protect with a vault policy". The vault controls are not turned on for your organization. Contact Safeguard support. Your credentials stay under Sandboxes, Cloud credentials.
A scan waits and then stops with APPROVAL_PENDING. The credential needs approval. Approve the request, then run the scan again. The runner waits native.approval_wait (10 minutes by default).
An API or host scan failed after a password change. The scan reads the credential once more after an authentication failure. If the second read returns the same old value, the change is not in the vault yet: add a new version, or check that your PAM has the new value.
The registered provider shows "Not seen yet" or "Not configured on runner X". The runner has not checked in, or its provider file has no provider with exactly that name. Check the runner is running and signed in, that SAFEGUARD_VAULT_CHECKIN is not off, and the names match.
Test access says "No runner answered within two minutes". The runner you picked is not running, is signed in to another organization, or has a different name (SAFEGUARD_RUNNER_NAME). Run safeguard secrets test on the runner to check the read itself.
"PAM credentials require on-prem runner execution." The target runs in Safeguard's cloud, which cannot reach your PAM. Under Where this scan runs, choose On-prem runner.
The runner is not listed under On-prem runner. Only runners that declared the scan type's capability are listed (dast, api, hostscan). Update the CLI on that machine (safeguard self-update) and restart the runner.
An on-prem DAST or API scan failed with runner_offline, runner_not_found or runner_did_not_pick_up. The chosen runner was offline, was removed, or did not claim the job within 10 minutes. Start it and run the scan again. The scan never falls back to the cloud.
A host scan stays queued. Its runner is offline. The scan starts when the runner comes back.
A host is skipped with "unknown host key". No credential was sent to it. Add its fingerprint (ssh-keyscan -t ed25519 <host> | ssh-keygen -lf -) or turn on Trust the host key on the first scan.
WinRM: "the WinRM service refused the credential (HTTP 401)". Basic authentication is not allowed for that account. Allow Basic over HTTPS on the host, or use a local account that may use it.
WinRM: TLS error. The runner does not trust the hosts' WinRM certificate. Install the issuing CA in the runner's system trust store (or pass --winrm-ca to safeguard hostscan).
The provider file is refused: "can be read by other users". Run chmod 600 ~/.safeguard/secret-providers.yaml.
The provider file is refused: "holds the secret setting ... inline". Move the value to a file or environment variable and write api_key: file:///path or api_key: env://NAME.
The provider file is refused: "a url that is refused". The url is plain http:// to another machine. Use https://. For a short test only, allow_http: true.
A value appears unredacted in my own tool's log. The runner redacts values of 6 characters or more from everything it writes and uploads. Use real credentials, and do not log in the target application what it receives.
Security model
Trust boundaries, what each component can see, how PAM credentials stay inside your network and out of logs and uploads, and the controls you have over what a runner may read.
Credentials vault CLI reference
The safeguard vault, safeguard secrets and safeguard hostscan commands, the /vault panel in the interactive terminal, and the runner's vault settings.