When the Safeguard CLI misbehaves, start with the doctor command. It checks your environment, sign-in, tools and policy, lists problems in order of importance, and changes nothing. Then read the log file, add the verbose option to the failing command, and work through the common causes below.
Step 1: run doctor
safeguard doctor
Its exit code is 0 whenever the checks ran, so do not use it as a pass or fail test in a pipeline. Read the lines instead. Save them when you ask for help:
safeguard doctor > doctor.txt
Step 2: get more output
Add the verbose option to the command that fails. The log file is kept at ~/.sg/logs/safeguard.log, and you can move it with the log directory variable.
Also note that notices and progress go to stderr. If JSON on stdout looks mixed with messages, redirect stdout only.
Step 3: match the symptom
Not authenticated, or a 401. The token expired or is missing. Run the whoami command, log out, then log in again with the force option. If the browser step hangs, use the no browser option.
Connection refused or a network error. Test connectivity to the auth endpoint with curl. Set the standard proxy variables if you are behind one, and allow outbound HTTPS on port 443.
Certificate error. Your network may use a corporate certificate authority the CLI does not trust. Point the SSL certificate file variable at your CA bundle, or add the certificate to the system trust store. The documentation advises against turning verification off.
No dependencies found. No manifests were detected, or you are in the wrong folder. Pass the directory explicitly and confirm manifest files exist.
Incomplete SBOM. Dependencies are not installed or lock files are missing. Install dependencies first and make sure lock files are present.
Out of memory. A large monorepo in one scan. Scan each package folder separately.
Image not found, or registry authentication failed. Check the reference, pull the image, or pass registry credentials.
Permission denied writing output. Choose an output folder you own.
Step 4: installation problems
If the shell says the command is not found, or the version is not what you expect, an older copy may be first on your PATH:
which -a safeguard
safeguard --version
If a scanner binary such as syft is not found on a fresh install, run safeguard interactively once and let first-run setup finish. The database update command refreshes existing scanners but does not install missing ones.
Step 5: ask for help with the right details
Collect the version output and the doctor file, plus the exact error and the steps that reproduce it. The CLI can open a support ticket for you, and the documentation also lists an email address for support.
Last resort: reset
Sign out, reset the configuration, delete the state folders and reinstall. This removes logs, history and the sign-in token, so only do it after the steps above.
Quick check
Doctor says everything is fine but my scan fails. Now what?
Doctor reports on the environment, not on your specific scan. Re-run the scan with the verbose option, read the log file, and check the output folder for partial results.
Why is my JSON output file invalid?
Messages may have been mixed in. Notices go to stderr, so redirect stdout alone, or use the output file option.
Safeguard also offers a free scan at gold.safeguard.sh/scan for a quick sanity check against a public repository.
Sources
Last reviewed: 19 October 2026.
