Troubleshooting CLI Issues

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

Enable Debug Mode

First, enable debug logging to get more information:

# Via environment variable
export SAFEGUARD_DEBUG=true
safeguard sbom generate --source .

# Or with --verbose flag
safeguard sbom generate --source . --verbose

Authentication Issues

"Authentication failed" or "Invalid API key"

Symptoms:

• Error message: "Authentication failed"
• HTTP 401 errors

Solutions:

1. Verify your API key is correct:

safeguard auth status

2. Re-authenticate:

safeguard auth logout
safeguard auth login

3. Check environment variable:

echo $SAFEGUARD_API_KEY

4. Ensure API key has required permissions in Settings → API Keys

"Token expired"

Solution:

safeguard auth refresh
# Or re-login
safeguard auth login

SSO Authentication Issues

If browser-based login fails:

1. Try the manual token flow:

safeguard auth login --manual

2. Copy the URL and open in browser manually
3. After authentication, paste the token back

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. Increase timeout:

safeguard config set api.timeout 600

2. Check for large projects that may need more time

3. Try scanning specific subdirectories instead of entire repository

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 sbom generate --source $(pwd)

3. Specify manifest file directly:

safeguard sbom generate --source . --manifest package.json

"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

3. Include development dependencies:

safeguard sbom generate --source . --include-dev

"Out of memory" Error

Solutions:

1. Scan subdirectories separately for monorepos:

safeguard sbom generate --source ./packages/app1
safeguard sbom generate --source ./packages/app2

3. Exclude unnecessary directories:

safeguard sbom generate --source . --ignore "test/**" --ignore "docs/**"

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-user $USERNAME \
  --registry-password $PASSWORD

3. Configure registry in config file:

registries:
  myregistry.azurecr.io:
    username: ${REGISTRY_USER}
    password: ${REGISTRY_PASSWORD}

Policy/Gate Issues

"Policy not found"

Solutions:

1. List available policies:

safeguard policy list

2. Use correct policy name:

safeguard gate check --source . --policy "Production Policy"

3. Create the policy in the web UI if it doesn't exist

Gate Failing Unexpectedly

Solutions:

1. Check detailed results:

safeguard gate check --source . --verbose

2. Review policy configuration in web UI

3. Check for approved exceptions:

safeguard gate check --source . --allow-exceptions

Output Issues

"Permission denied" When Writing Output

Solutions:

1. Check directory permissions:

ls -la ./sbom/
mkdir -p ./sbom && chmod 755 ./sbom

2. Specify a different output location:

safeguard sbom generate --source . --output ~/sbom/output.json

Malformed Output

Solutions:

1. Specify format explicitly:

safeguard sbom generate --source . --format cyclonedx-json

2. Check for console output interference:

safeguard sbom generate --source . --quiet --output sbom.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 diagnostics > diagnostics.txt

This collects:

• CLI version
• OS and architecture
• Configuration (with secrets redacted)
• Recent log entries

Contact Support

If issues persist:

1. Email hi@safeguard.sh with:

   • Diagnostic output
   • Error messages
   • Steps to reproduce

2. Include relevant log files from ~/.safeguard/logs/

Reset Everything

As a last resort, reset the CLI completely:

# Remove local state: session, logs, history
rm -rf ~/.sg

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

Remove-Item "$env:USERPROFILE\.sg" -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.