Safeguard Docs
Credentials Vault

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 did

Every 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

CodeMeaningWhat to do
NOT_CONFIGUREDThe 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_FAILEDThe 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.
FORBIDDENThe 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_FOUNDThe 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/.
TLSThe 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.
UNREACHABLENo 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.
TIMEOUTThe PAM did not answer within timeout (default 15 s), after the retries.Raise timeout, check the PAM's health.
BAD_REFERENCEThe reference is malformed, or names a field the provider does not have.Compare with the reference format on the provider's page.
DISABLEDenv:// 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.
EMPTYThe 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_ALLOWEDThe 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.

CodeMeaningWhat to do
NOT_PERMITTEDThe 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_BOUNDThe 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_ALLOWEDThe 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_PENDINGThe 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_DENIEDAn approver denied the request.Read the comment on the request. Ask again with a reason if the use is right.
SCAN_CONTEXT_REQUIREDAn 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_REQUIREDA 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_BOUNDA 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_APPROVALYou tried to approve your own request.Ask another approver.
LEASE_HELDThe 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_REQUIREDThe 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_ONLYYou 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_REQUIREDThe 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_MANAGEAn 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_BOUNDA 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_FOUNDA source-code integration token names a credential that does not exist or that you cannot see.Pick the credential again.
PAM_NOT_SUPPORTED_FOR_SCMA 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_UNAVAILABLESafeguard 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.

On this page