Skip to main content

Troubleshooting

Common issues, error messages, and their resolutions. When reporting bugs, always include the output of arcan doctor.

Quick Diagnostics​

Run these commands first to identify the problem area:

arcan doctor                  # check all local subsystems
arcan auth test <provider>    # test SSO provider connectivity
arcan doctor --data-dir /path # check a custom data directory

arcan doctor verifies six subsystems: master key, database, TLS CA certificate, TLS server certificate, AES-256-GCM encryption round-trip, and plugin discovery. A failing check narrows the problem immediately.

Connection Issues​

"request failed: connection refused"​

Cause: The Arcan server is not running.

Fix:

arcan server

If the server was previously running, it may have crashed. Check logs or start it again.

"request failed: dial tcp: i/o timeout"​

Cause: Wrong server URL, firewall blocking the port, or network issue.

Fix:

  1. Verify the server URL: 
    arcan kv list --api-url https://localhost:8081
  2. Check that port 8081 (default) is not blocked by a firewall.
  3. If running remotely, ensure the host is reachable: curl -k https://<host>:8081/api/v1/health

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

Cause: Arcan auto-generates a self-signed TLS certificate on first run. External tools (curl, browsers, SDKs) do not trust it by default.

Note: The Arcan CLI trusts self-signed certificates automatically. This error typically comes from external clients.

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

# RHEL/CentOS
sudo cp ~/.arcan/data/ca/ca.crt /etc/pki/ca-trust/source/anchors/arcan-ca.crt
sudo update-ca-trust

Fix (skip verification for testing):

curl -k https://localhost:8081/api/v1/health

"Is the server running? Start with: arcan server"​

Cause: The CLI could not reach the API at all. This is appended to any HTTP request failure.

Fix:

  1. Start the server: arcan server
  2. If the server is on a different host or port, specify: --api-url https://host:port
  3. Check ~/.arcan/config.json for a stale api_url value.

Authentication Errors​

"invalid email or password"​

Cause: Wrong credentials during POST /api/v1/auth/login.

Fix:

  • Double-check email and password.
  • Passwords must be at least 12 characters.
  • If you forgot your password, ask an admin to reset it (or re-register if using open registration).

"missing authentication"​

Cause: No Authorization: Bearer <token> header on a request that requires auth.

Fix:

arcan login

This stores the token in ~/.arcan/config.json. All subsequent CLI commands use it automatically.

"invalid or expired token"​

Cause: The JWT or API token has expired or been revoked. JWTs expire after 24 hours.

Fix:

arcan login          # get a new JWT
arcan token list     # check if API tokens are still valid

"registration is disabled"​

Cause: The server's registration policy is set to disabled. No new accounts can be created via the API.

Fix: Ask the administrator to either:

  • Change the policy to open or admin-only in config.
  • Create your account directly.
  • Configure SSO so you can log in via OIDC, SAML, or LDAP.

"registration requires admin approval"​

Cause: The default registration policy is admin-only. Only the first user (the admin) can self-register. Subsequent users need admin approval.

Fix:

  • Ask the admin to create your account.
  • Use SSO (OIDC, SAML, or LDAP) -- SSO logins auto-create users.

"email already registered"​

Cause: An account with that email already exists.

Fix: Log in instead of registering: arcan login

"token not found"​

Cause: The API token ID does not exist or belongs to a different user.

Fix:

arcan token list     # list your valid tokens

SSO / OIDC Errors​

"OIDC is not configured"​

Cause: No OIDC providers are defined in the server configuration.

Fix:

arcan auth setup --type oidc --name <provider> \
  --issuer <url> --client-id <id> --client-secret "$SECRET"

# Or use the interactive wizard:
arcan auth setup

"OIDC provider not found"​

Cause: The provider name in the URL does not match any configured OIDC provider.

Fix:

  1. Check configured providers: look at ~/.arcan/config.yaml under auth.oidc.
  2. Re-run setup if the name is wrong: arcan auth setup

"OIDC authentication failed"​

Cause: The OIDC token exchange failed. Common reasons:

  • Invalid client_id or client_secret.
  • Wrong redirect URL (must match exactly what the IdP expects).
  • User's email domain is not in the allowed_domains list.
  • The authorization code expired (codes are single-use and short-lived).

Fix:

arcan auth test <provider>           # test connectivity
arcan auth test <provider> --debug   # verbose output

Check that:

  • The client_id and client_secret match what is configured in your identity provider console.
  • The redirect URL is https://<arcan-host>/api/v1/auth/oidc/<provider>/callback.
  • The user's email domain is in allowed_domains (or remove the restriction).

"OIDC Discovery failed"​

Cause: The /.well-known/openid-configuration endpoint is unreachable or returned an error.

Fix:

  1. Verify the issuer URL is correct (no trailing slash issues).
  2. Test manually: curl <issuer>/.well-known/openid-configuration
  3. Check network connectivity and DNS resolution.

"invalid OIDC state -- possible CSRF attack"​

Cause: The state parameter from the callback does not match the one stored in the cookie. This can happen if:

  • The user took too long to authenticate (cookie expired after 5 minutes).
  • The browser blocked the arcan_oidc_state cookie (SameSite/Secure settings).
  • An actual CSRF attempt.

Fix: Try logging in again from the beginning.

SSO / SAML Errors​

"SAML is not configured"​

Cause: No SAML providers are defined in the server configuration.

Fix:

arcan auth setup --type saml --name <provider> \
  --acs-url <url> --metadata-url <metadata-url>

"SAML authentication failed"​

Cause: The SAML assertion could not be validated. Common reasons:

  • Wrong ACS URL (must match exactly what the IdP sends assertions to).
  • Clock skew between Arcan server and IdP (assertions have time-based validity).
  • IdP metadata is stale or mismatched.
  • The SAML response signature could not be verified.

Fix:

  1. Verify the ACS URL matches: https://<arcan-host>/api/v1/auth/saml/<provider>/acs
  2. Check time synchronization: date -u on both servers.
  3. Re-fetch IdP metadata if it has changed.
  4. Check the SP metadata at: GET /api/v1/auth/saml/<provider>/metadata

"SAML Metadata fetch failed"​

Cause: The IdP metadata URL is unreachable or returned invalid XML.

Fix:

  1. Test the URL manually: curl <metadata-url>
  2. If using a metadata file instead, check the file path and ensure it contains valid XML.
  3. Some IdPs require authentication to access metadata -- use --metadata-file with a downloaded copy.

SSO / LDAP Errors​

"LDAP is not configured"​

Cause: No LDAP providers are defined in the server configuration.

Fix:

arcan auth setup --type ldap --name <provider> \
  --ldap-url ldaps://<host>:636 \
  --bind-dn "<dn>" --bind-password "$PW" --base-dn "<dn>"

"LDAP authentication failed"​

Cause: The user could not be authenticated against the LDAP directory. Common reasons:

  • Wrong username or password.
  • User not found under the configured base_dn.
  • Service account (bind_dn) credentials are wrong.
  • User filter does not match the user's attributes.

Fix:

arcan auth test <provider>         # test bind credentials
arcan auth test <provider> --debug # verbose output

Common Active Directory issues:

  • sAMAccountName vs UPN: AD users can log in with either jdoe (sAMAccountName) or [email protected] (UPN). Make sure the user filter matches the format you expect.
  • Nested groups: If using required_group, ensure the user is a direct member or configure recursive group search.
  • Referrals: Large AD forests may return referrals. Ensure the LDAP URL points to a Global Catalog server (port 3268/3269) if needed.

"LDAP connection test failed"​

Cause: Cannot connect to the LDAP server or bind with the service account.

Fix:

  1. Check the hostname and port: ldapsearch -H ldaps://<host>:636 -x -D "<bind-dn>" -w "<pw>" -b "<base-dn>"
  2. Verify TLS: if using ldaps://, ensure the LDAP server's certificate is trusted.
  3. Check firewall rules for port 636 (LDAPS) or 389 (LDAP).
  4. Verify the bind DN and password are correct.

Secret / Encryption Errors​

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

Cause: The master key file is missing, corrupted, or has wrong permissions.

Fix:

arcan doctor   # check master key status

The doctor output will tell you exactly what is wrong:

  • "not found": The file ~/.arcan/data/master.key does not exist. Run arcan server to auto-generate it on first start.
  • "N bytes, expected 32": The key file is corrupted. It must be exactly 32 bytes (256 bits).
  • "permissions 0644, expected 0600": Fix permissions: chmod 600 ~/.arcan/data/master.key

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

Cause: Secrets were encrypted with a different master key than the one currently loaded. This happens if:

  • The master key file was replaced or regenerated.
  • You are pointing at a different data directory.

Fix:

  • Restore the original master key from backup.
  • If the key is lost, encrypted secrets are unrecoverable (this is by design -- zero-knowledge encryption).

"key and value are required"​

Cause: The key or value field is empty in a secret set request.

Fix:

arcan kv set MY_KEY "my-value"                    # CLI
arcan kv set MY_KEY "my-value" --env prod         # with environment

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

Cause: An invalid environment name was provided.

Fix: Use one of: dev, staging, prod, test. Example:

arcan kv set DB_URL "postgres://..." --env prod

"secret not found"​

Cause: No secret with that key exists in the specified realm and environment.

Fix:

arcan kv list                    # list secrets in default realm/env
arcan kv list --env prod         # list secrets in prod
arcan kv list -r my-realm        # list secrets in a specific realm

Realm Errors​

"realm not found"​

Cause: The realm slug does not exist or is not accessible to the current user.

Fix:

arcan realm list                 # list available realms
arcan realm create <slug> <name> # create a new realm

The default realm is auto-created on first use. If you see this error with a custom realm, check the slug for typos.

RBAC / Policy Errors​

"insufficient permissions -- requires capability"​

Cause: Your user account does not have the required capability (e.g., secrets:write, secrets:read, secrets:delete) in the requested realm.

Fix: Ask a realm admin to grant you the appropriate role:

arcan policy bind -r <realm> --user-id <your-id> --role member

Available roles and their capabilities depend on the policy configuration. Common roles:

  • admin: full access to the realm.
  • member: read and write secrets.
  • viewer: read-only access.

Note: Realm owners (the user who created the realm) are automatically treated as admins, even without an explicit role binding.

Plugin Errors​

"engine not found"​

Cause: The requested plugin/engine is not installed or not discovered in the plugins directory.

Fix:

arcan plugin list                        # list installed plugins
ls ~/.arcan/data/plugins/                # check plugin directory

Plugins must be executable files in the plugins directory. Check file permissions:

chmod +x ~/.arcan/data/plugins/<plugin-name>

Doctor Failures​

Master Key: "not found"​

The master key has not been generated yet.

Fix: Start the server once to auto-generate it: arcan server

Master Key: "permissions 0644, expected 0600"​

The key file is world-readable, which is a security risk.

Fix:

chmod 600 ~/.arcan/data/master.key

Database: "not found"​

The SQLite database has not been created yet.

Fix: Start the server once: arcan server. The database and migrations are applied automatically.

Database: "expected WAL mode"​

The database is not using WAL (Write-Ahead Logging) mode.

Fix: This is set automatically on creation. If it was changed externally:

sqlite3 ~/.arcan/data/arcan.db "PRAGMA journal_mode=WAL;"

TLS CA / TLS Server: "not found"​

TLS certificates have not been generated yet.

Fix: Start the server once: arcan server. Certificates are auto-generated on first run.

TLS CA / TLS Server: "expired"​

The auto-generated certificate has expired.

Fix: Delete the old certificates and restart the server to regenerate them:

rm ~/.arcan/data/ca/ca.crt ~/.arcan/data/ca/ca.key
rm ~/.arcan/data/tls/server.crt ~/.arcan/data/tls/server.key
arcan server

TLS CA / TLS Server: "invalid PEM"​

The certificate file is corrupted.

Fix: Delete and regenerate (same as expired fix above).

Encryption: "round-trip mismatch" or "encrypt/decrypt failed"​

The encryption subsystem is broken, likely due to a corrupted master key.

Fix:

  1. Check the master key: arcan doctor (look at the Master Key line).
  2. If the key is the wrong size, restore from backup.
  3. If no backup exists, generate a new key -- but all existing encrypted data will be unrecoverable.

Server Issues​

"address already in use"​

Cause: Another process is already using port 8081 (or whichever port Arcan is configured to use).

Fix:

# Find what is using the port
lsof -ti :8081

# Kill it (if safe to do so)
lsof -ti :8081 | xargs kill

# Or start Arcan on a different port
ARCAN_PORT=9090 arcan server

"migration applied" messages on every start​

Normal behavior. On first startup (or after an upgrade), Arcan applies database migrations. These messages are informational and appear once per migration.

"could not find server process on port"​

Cause: During arcan auth setup, the wizard tried to signal the running server to reload, but could not find the server process.

Fix:

  • If the server is running on a non-default port, specify --api-url.
  • Restart the server manually: Ctrl+C, then arcan server.

Server crashes or hangs​

  1. Check disk space: SQLite needs room for WAL files.
  2. Check file descriptor limits: ulimit -n (should be at least 1024).
  3. Run arcan doctor to verify all subsystems.
  4. Start with debug logging: arcan server --debug

Debug Mode​

For any command, add --debug to get verbose output:

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

Debug mode shows:

  • HTTP request method, URL, and response status.
  • API paths being called.
  • Full error details including stack context.
  • Configuration file paths being used.
  • TLS and connection details.

Common Paths​

PathPurpose
~/.arcan/config.jsonCLI configuration (API URL, token)
~/.arcan/config.yamlServer and SSO configuration
~/.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​