Troubleshooting CLI Issues

This guide helps you diagnose and resolve common issues with the Safeguard CLI.

Start with doctor

safeguard doctor checks the environment, sign-in, tools and policy and prints what is wrong, most important first. It changes nothing:

safeguard doctor

For more detail while a scan runs, add --verbose:

safeguard scan --dir . --verbose

Every run also writes a structured log to ~/.sg/logs/safeguard.log.

Authentication Issues

"Not authenticated" or HTTP 401

1. See who you are signed in as, and whether the token has expired:

safeguard whoami

2. Sign in again. --force re-authorizes even when a session exists, which is also how you switch accounts:

safeguard logout
safeguard login --force

The CLI does not read an API key from the environment. A machine is authorized by signing in with /login or safeguard login.

Browser sign-in does not open or does not finish

Use the device code by hand:

safeguard login --no-browser

The CLI prints a verification URL and a short code. Open the URL on any device, enter the code, approve, and the CLI picks up the session.

Network Issues

"Connection refused" or "Network error"

Solutions:

1. Check internet connectivity:

curl -I https://api.safeguard.sh/auth

2. Configure proxy if behind corporate firewall:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

3. Check firewall rules allow outbound HTTPS (port 443)

"Certificate error" or "SSL handshake failed"

Solutions:

1. Point the CLI at a custom CA bundle:

export SSL_CERT_FILE=/path/to/corporate-ca.crt

2. Update system CA certificates — the CLI uses the system trust store, so installing the certificate there fixes it for every tool at once:

# Ubuntu/Debian
sudo update-ca-certificates

# macOS
security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/cert.crt

3. If neither works, contact support with the output of safeguard --version and the full error.

Timeout Errors

Solutions:

1. Scan a subdirectory instead of the whole repository:

safeguard scan --dir ./services/api

2. Skip transitive resolution, which makes network calls for every dependency, unless you need it (it is off unless you pass --resolve-transitive).

Scanning Issues

"No dependencies found"

Possible causes:

• No manifest files in the directory
• Manifest files not recognized
• Wrong directory specified

Solutions:

1. Verify manifest files exist:

ls -la package.json requirements.txt pom.xml go.mod Cargo.toml

2. Check you're in the correct directory:

pwd
safeguard scan --dir "$(pwd)"

"Unsupported package manager"

Solution: Check the support matrix for supported package managers.

Incomplete SBOM (Missing Dependencies)

Solutions:

1. Install dependencies first:

# Node.js
npm install

# Python
pip install -r requirements.txt

# Go
go mod download

2. Include lock files:

# Ensure lock files exist
ls -la package-lock.json yarn.lock Pipfile.lock

"Out of memory" Error

Solutions:

1. Scan subdirectories separately for monorepos:

safeguard scan --dir ./packages/app1
safeguard scan --dir ./packages/app2

Container Scanning Issues

"Image not found"

Solutions:

1. Verify image exists:

docker images | grep myimage

2. Pull the image first:

docker pull myimage:latest
safeguard scan --image myimage:latest

3. Use full image reference:

safeguard scan --image docker.io/library/nginx:latest

"Registry authentication failed"

Solutions:

1. Login to registry first:

docker login myregistry.azurecr.io

2. Provide credentials:

safeguard scan --image myregistry.azurecr.io/app:v1 \
  --registry-username "$USERNAME" \
  --registry-password "$PASSWORD"

Policy and gate issues

The CLI has no policy or gate command. Policies and gates are defined and evaluated in the platform, on the scans it runs and the results the runner uploads. See Policies & gates for how to see why a gate failed and how exceptions are approved.

Output Issues

"Permission denied" When Writing Output

Write somewhere you own:

safeguard scan --dir . --output ~/safeguard-results

JSON on stdout is mixed with messages

Commands write machine-readable JSON to stdout and every notice and log line to stderr, so redirect stdout alone:

safeguard detect --format json > detect.json

Installation Issues

"Command not found: safeguard"

Solutions:

1. Find every copy on your PATH:

which -a safeguard

Get-Command safeguard -All

2. If more than one appears, the first wins. An old build under ~/go/bin shadowing the installed one is the usual cause — check what each reports:

safeguard --version

3. If none appears, the install directory is not on your PATH. Open a new shell first (the Windows installer adds its directory to the user PATH, which existing shells do not pick up), then reinstall if it is still missing:

curl -fsSL https://cli.safeguard.sh/install | bash

"syft binary not found" on a fresh install

Symptoms:

• A scan fails immediately on a machine where the CLI was just installed

Cause:

The CLI downloads its scanner toolchain the first time it needs it. A freshly installed binary has no scanners yet.

Solution:

Open the interactive terminal once and let first-run setup finish:

safeguard

Getting More Help

Collect diagnostic information

safeguard --version
safeguard doctor > doctor.txt

Contact support

Raise it from the CLI, which files it on the same queue as the product's Help & Feedback sheet:

safeguard support bug "what you ran, what you expected, what happened"

Or email hi@safeguard.sh with the doctor output, the error and the steps to reproduce. The log file is ~/.sg/logs/safeguard.log.

Reset Everything

As a last resort, reset the CLI completely:

# Sign out and remove the deployment config
safeguard logout --yes
safeguard config reset --yes

# Remove local state: logs, history, sign-in token
rm -rf ~/.sg ~/.scanner

# Reinstall over the top
curl -fsSL https://cli.safeguard.sh/install | bash

Remove-Item "$env:USERPROFILE\.sg", "$env:USERPROFILE\.scanner" -Recurse -Force
irm https://cli.safeguard.sh/install.ps1 | iex

Then open the terminal and sign in again:

safeguard

Type /login, then /doctor to confirm health and connectivity.