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 Arcan CA certificate on your system. Run arcan doctor to see the CA certificate location, then add it to your system trust store:

# macOS
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain <ca-cert-path>

# Ubuntu/Debian
sudo cp <ca-cert-path> /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: Run arcan doctor to diagnose. Start the server to auto-generate the key (arcan server), or verify file permissions with arcan doctor.

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 8443. Fix: lsof -ti :8443 | xargs kill or ARCAN_PORT=9090 arcan server.

10. "engine not found"​

Plugin is not installed. Fix: arcan plugin list to see installed plugins. Install the missing plugin from the registry.

11. Server starts but produces no output​

The server is waiting on a database connection (TCP timeout, typically 30 seconds). This usually means PostgreSQL is unreachable.

Fix: Verify your database is running and the connection URL is correct. Check with psql $DATABASE_URL first. The server now logs "connecting to PostgreSQL..." on startup — if you don't see that message, check that DATABASE_URL or ARCAN_DATABASE_URL is set.

12. "environment must be dev, staging, prod, or test"​

Invalid environment value. Arcan accepts: dev, staging, prod, test. Common aliases production and development are automatically normalized to prod and dev.

13. "no config file found, using environment variables"​

This is informational, not an error. Arcan looks for a config file on startup. If not found, all configuration comes from environment variables and CLI flags. This is the recommended approach for production deployments.

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

Data Directory​

All Arcan data is stored under ~/.arcan/. Use arcan doctor to verify the data directory structure and permissions. Use --data-dir to override the default location.

Getting Help​