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:

Verify your API key is correct:

safeguard auth status

Re-authenticate:

safeguard auth logout
safeguard auth login

Check environment variable:

echo $SAFEGUARD_API_KEY

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:

Try the manual token flow:

safeguard auth login --manual

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

Network Issues

"Connection refused" or "Network error"

Solutions:

Check internet connectivity:

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

Configure proxy if behind corporate firewall:

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

Check firewall rules allow outbound HTTPS (port 443)

"Certificate error" or "SSL handshake failed"

Solutions:

For custom CA certificates:

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

Temporarily disable certificate validation (not recommended for production):

export NODE_TLS_REJECT_UNAUTHORIZED=0

Update system CA certificates:

# Ubuntu/Debian
sudo update-ca-certificates

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

Timeout Errors

Solutions:

Increase timeout:

safeguard config set api.timeout 600

Check for large projects that may need more time
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:

Verify manifest files exist:

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

Check you're in the correct directory:

pwd
safeguard sbom generate --source $(pwd)

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:

Install dependencies first:

# Node.js
npm install

# Python
pip install -r requirements.txt

# Go
go mod download

Include lock files:

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

Include development dependencies:

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

"Out of memory" Error

Solutions:

Increase Node.js memory:

export NODE_OPTIONS="--max-old-space-size=4096"

Scan subdirectories separately for monorepos:

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

Exclude unnecessary directories:

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

Container Scanning Issues

"Image not found"

Solutions:

Verify image exists:

docker images | grep myimage

Pull the image first:

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

Use full image reference:

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

"Registry authentication failed"

Solutions:

docker login myregistry.azurecr.io

Provide credentials:

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

Configure registry in config file:

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

Policy/Gate Issues

"Policy not found"

Solutions:

List available policies:

safeguard policy list

Use correct policy name:

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

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

Gate Failing Unexpectedly

Solutions:

Check detailed results:

safeguard gate check --source . --verbose

Review policy configuration in web UI
Check for approved exceptions:

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

Output Issues

"Permission denied" When Writing Output

Solutions:

Check directory permissions:

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

Specify a different output location:

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

Malformed Output

Solutions:

Specify format explicitly:

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

Check for console output interference:

safeguard sbom generate --source . --quiet --output sbom.json

Installation Issues

"Command not found: safeguard"

Solutions:

Verify installation:

npm list -g @safeguard-sh/cli

Check PATH:

echo $PATH
which safeguard

Reinstall globally:

npm uninstall -g @safeguard-sh/cli
npm install -g @safeguard-sh/cli

Try npx:

npx @safeguard-sh/cli sbom generate --source .

Node.js Version Issues

Symptoms:

Syntax errors
Module not found errors

Solution:

Check Node.js version (requires 18+):

node --version

Update Node.js if needed:

# Using nvm
nvm install 18
nvm use 18

Getting More Help

Collect Diagnostic Information

safeguard diagnostics > diagnostics.txt

This collects:

CLI version
Node.js version
OS information
Configuration (with secrets redacted)
Recent log entries

Contact Support

If issues persist:

Email hi@safeguard.sh with:
- Diagnostic output
- Error messages
- Steps to reproduce
Include relevant log files from ~/.safeguard/logs/

Reset Everything

As a last resort, reset the CLI completely:

# Remove configuration
rm -rf ~/.safeguard

# Reinstall
npm uninstall -g @safeguard-sh/cli
npm install -g @safeguard-sh/cli

# Reconfigure
safeguard config init
safeguard auth login

Troubleshooting CLI Issues

On this page