Troubleshooting

Could not reach http://localhost:8000 means no BBM-Atlas answered there. Start one with bbm-atlas serve, or point the CLI at yours with --base-url (or BBM_ATLAS_CLI_BASE_URL). bbm-atlas health checks the connection.

A 401: the server requires keys and this request carried none it accepts. Give the CLI one with BBM_ATLAS_CLI_API_KEY, the console with its API key button, and an assistant through its MCP configuration (Connect your AI assistant). An Enterprise key may have expired or been revoked: Invalid, expired or revoked API key.

A 403 with a key the server accepted: the key's role doesn't grant what the request needs, and the message names the permission. bbm-atlas enterprise whoami shows a key's roles and permissions; an administrator can change them (People, roles and keys).

… is outside the configured index roots is a 403 too: the server only indexes under BBM_ATLAS_INDEX_ROOTS.

The local store … is in use by another BBM-Atlas process - only one process opens the local store at a time. Use the one that has it: its REST API, or its /mcp endpoint for assistants, instead of a second serve or a stdio mcp serve. Or stop it first, or give the other process its own BBM_ATLAS_LOCAL_STORE_PATH.

… was written by a newer BBM-Atlas - upgrade this installation (pip install --upgrade bbm-atlas), or point it at another file.

BBM_ATLAS_API_KEYS must be set when BBM_ATLAS_ENVIRONMENT=production - set keys, or a file of them with BBM_ATLAS_API_KEYS_FILE (Security).

A 429 means this caller spent its budget for the current minute; Retry-After says how many seconds to wait. Each key and each signed-in account has its own budget, while requests without a working key share their address's - so a script sending a mistyped key soon runs out. Raise BBM_ATLAS_RATE_LIMIT_REQUESTS_PER_MINUTE if the budget is too small for real use.

• Check the address: the running API's /mcp, http://127.0.0.1:8000/mcp by default. The console's overview page shows this server's.
• On a server reached by name, the name must be in BBM_ATLAS_MCP_ALLOWED_HOSTS, or /mcp refuses the request.
• With keys required, the host must send one as Authorization: Bearer or X-API-Key.

/health/ready answers 503 while a store is unreachable, with each store's status, so it names the one at fault: check that database's address and credentials. bbm-atlas ready asks the same.

• The console shows the reason after a failed sign-in, and the audit log records it as sso.sign_in with the outcome failure.
• The redirect URL (OIDC) or the ACS URL (SAML) must be registered with the provider exactly as configured, scheme and path included.
• A disabled user can't sign in. A user with no roles signs in, but can do nothing until given roles.
• SAML responses must be signed and not encrypted, and the server's clock right to within two minutes.

bbm-atlas enterprise license prints the state and the reason: missing (no key set where BBM-Atlas looks), invalid (damaged, or not signed by a key this version knows), or expired past its grace period. Check that the variable or file reaches the process. For a new or renewed key, write to info@byteblendmatrix.com.

Run with BBM_ATLAS_LOG_LEVEL=DEBUG and look at the log for the request, by its X-Request-ID. Then write to info@byteblendmatrix.com with the message, what you ran, and your version (bbm-atlas --version).