Skip to main content

Troubleshooting

Quick Diagnostics​

arcan doctor                  # check all local subsystems
arcan auth test <provider>    # test SSO connectivity
arcan <any-command> --debug   # verbose output

Top 10 Common Errors​

1. "request failed: connection refused"​

Server is not running. Fix: arcan server

2. "request failed: tls: failed to verify certificate"​

External tools do not trust Arcan's auto-generated self-signed cert. The CLI handles this automatically.

Fix (trust the CA):

# macOS
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ~/.arcan/data/ca/ca.crt

# Ubuntu/Debian
sudo cp ~/.arcan/data/ca/ca.crt /usr/local/share/ca-certificates/arcan-ca.crt
sudo update-ca-certificates

3. "invalid or expired token"​

JWT expired (24h lifetime) or API token was revoked.

Fix: arcan login to get a new token.

4. "encryption failed -- verify the master key is configured"​

Master key file is missing, corrupted, or has wrong permissions. Run arcan doctor to see which.

Fix: Start the server to auto-generate (arcan server), or fix permissions (chmod 600 ~/.arcan/data/master.key).

5. "decryption failed -- the master key may have changed"​

Secrets were encrypted with a different master key. Restore the original key from backup. If lost, encrypted secrets are unrecoverable (by design).

6. "realm not found"​

The realm slug does not exist or is inaccessible. Fix: arcan realm list to see available realms.

7. "insufficient permissions -- requires capability"​

Your role lacks the needed capability. Fix: Ask a realm admin: arcan policy bind -r <realm> --user-id <id> --role member

8. "OIDC authentication failed"​

Common causes: wrong client ID/secret, mismatched redirect URL, or email domain not in allowed_domains.

Fix: arcan auth test <provider> --debug and verify settings match your IdP configuration.

9. "address already in use"​

Another process is on port 9797. Fix: lsof -ti :9797 | xargs kill or ARCAN_PORT=9090 arcan server.

10. "engine not found"​

Plugin is not installed. Fix: arcan plugin list and check ~/.arcan/data/plugins/.

Debug Mode​

Add --debug to any command for verbose output:

arcan kv set KEY "value" --debug
arcan auth test okta --debug

Debug mode shows HTTP request/response details, API paths, full error context, config file paths, and TLS details.

arcan doctor​

Run arcan doctor to verify six subsystems without a running server:

  1. Master key -- exists, 32 bytes, 0600 permissions
  2. Database -- opens, responds to ping, WAL mode
  3. TLS CA cert -- valid, not expired
  4. TLS server cert -- valid, not expired
  5. Encryption -- AES-256-GCM round-trip test
  6. Plugins -- directory scan

Common Paths​

PathPurpose
~/.arcan/config.jsonCLI config (API URL, token)
~/.arcan/config.yamlServer and SSO config
~/.arcan/data/master.keyMaster encryption key (32 bytes, 0600)
~/.arcan/data/arcan.dbSQLite database
~/.arcan/data/ca/ca.crtAuto-generated CA certificate
~/.arcan/data/tls/server.crtAuto-generated server certificate
~/.arcan/data/plugins/Plugin directory

Getting Help​