Troubleshooting

CLI Issues

"Command not found"

Verify the CLI is installed:

npm list -g @tensflare/cli

If missing, install or reinstall:

npm install -g @tensflare/cli

"Authentication required"

You are not authenticated. Run the login command:

truss auth login

Alternatively, set credentials via environment variables:

export TRUSS_API_URL=http://localhost:4000
export TRUSS_API_KEY=tr_abc123

"API request failed"

The CLI cannot reach the API server. Check that TRUSS_API_URL is set correctly and the server is running:

echo $TRUSS_API_URL
curl -I $TRUSS_API_URL

"Config not found"

Configuration is stored at ~/.config/truss/config.json. Verify the file exists:

ls -la ~/.config/truss/config.json

If missing, re-run truss auth login to regenerate it.

Shell completion not working

Ensure you have sourced the completion script for your shell:

# For zsh
source <(truss completion zsh)

# Add to ~/.zshrc to persist
echo 'source <(truss completion zsh)' >> ~/.zshrc

API Issues

401 Unauthorized

The API key is invalid, expired, or missing. Generate a new key and update your configuration.

403 Forbidden

Your RBAC role does not permit this action. Contact an administrator to request elevated permissions.

404 Not Found

The requested resource does not exist or you do not have access to it. Verify the resource identifier and your permissions.

409 Conflict

The resource is in a state that prevents the requested operation. For example, deleting an agent that still has active mandates assigned. Resolve the conflict before retrying.

Evidence & Verification

"Chain integrity compromised"

One or more action records in the chain have been tampered with or the chain is broken. Re-verify the package:

truss verify package <id>

"Signature invalid"

The cryptographic signature does not match the data, or the signing key has been rotated. Confirm you are using the correct public key for verification and that the evidence has not been modified.

Mandate verification fails

Ensure the issuing agent's Ed25519 public key is current and registered with Truss. Expired or rotated keys will cause verification to fail.

PreviousGlossaryNextSdk