Authentication
401 Unauthorized
The credential is missing, expired, or belongs to a different API. Check, in
order: which base URL you are calling (albus status), whether ALBUS_API_KEY is
exported and current, and whether the stored session is still good
(albus whoami). Remember the CLI prefers an exported ALBUS_API_KEY over the
stored session — an old key in your shell beats a fresh albus login.
albus whoami names an API key rather than me
Expected. whoami reports whichever credential precedence resolved, and an
exported ALBUS_API_KEY wins over the stored session; unset it to be named as
yourself. tokens and invites identify you, so they take the browser
session only and refuse a key with 401.
no Auth0 tenant configured for <url>
albus login has no sign-in configuration for that base URL. Check --base-url
and ALBUS_BASE_URL; if you are pointing at a local server, export the
ALBUS_AUTH0_* variables for it.
could not listen for the sign-in redirect on 8484, 8485, 8486, 8487
Every loopback port albus login uses is taken. Close whatever holds them, or use
albus login --no-browser and open the URL yourself.
no sign-in completed within 180 seconds
The browser never delivered the redirect. Run it again. If the message adds
“N redirect(s) carried another state”, a stale tab from an earlier sign-in
answered instead — close it first.
Running sessions
423 — another invocation is currently running
A session runs one invocation at a time. Wait for it, retry with the running
invocation’s key to attach to it, or use a different session id.
Concurrency belongs across sessions, not within one.
409 — invocation key reused with a different body
The same key was already used for a different prompt or agent configuration.
Use a new key, or resend exactly the original body.
429 — quota exceeded
The organization has reached its run limit. Retrying will not help; contact
carlo@albus.sh to raise it.
504 — timed out waiting for the assistant response
Your wait_timeout_seconds elapsed (CLI: --wait-timeout); the run continues.
Retry the same invocation key to re-attach, or poll albus sessions get. Do
not start a new key — you would run the prompt twice.
502 — the run failed instead of producing a response
The body carries the failure kind and detail, and Albus already retried the
invocation up to three times — every attempt failed. Look at
GET /traces/{invocation_key} (with attempts=all for the earlier attempts), or
at albus sessions audit <session> for the last model_call/tool_call and the
invocation_failed event. Then run again with a new invocation key; reusing
the failed key replays the failure.
400 — invalid request
Something was rejected before anything ran: an unknown tool name, an MCP server
with a missing, duplicated, or __-containing name, a url that is not an
absolute http(s) URL, a missing model, a model Albus does not serve
(albus models list), an output_format schema that leaves
additionalProperties unset or a property out of required, or a malformed
secret reference.
The invocation fails immediately, with no model call in the audit log
A secret reference names a secret that does not exist. References are resolved
when the run starts, not when the request is validated, so a missing secret fails
the run rather than the request. albus secrets list shows what exists.
--agent-file holds the whole agent configuration and cannot be combined with the other agent options
Move --model (and any other agent flag) into the JSON file.
--model is required unless --agent-file is given / --provider and --credential must be given together
Exactly what they say.
Secrets and MCP
invalid secret reference
A credential field got something that is not albus.sh/secrets/<name>. Provider
credentials must be references; MCP header values may be literals.
invalid secret name
Names are /-separated segments of [a-zA-Z0-9_-], up to 255 characters, with no
empty, ., or .. segments. No leading or trailing slash.
The agent never calls an MCP tool
Either the tool is not in allowed_tools (omit the field to allow all of them),
or the prompt gave the model no reason to call it. albus sessions audit shows
which tools were called.
The MCP server rejects Albus’s calls (mcp_auth_rejected in the audit log)
One of three causes. With the default identity token, the server’s verifier is
not configured for your issuer (https://oidc.albus.sh/organizations/<org-id>,
under Settings → Organization), or the verifier’s audience differs from the
declared url — trailing slash and query included. With a headers.Authorization
entry, the header value is wrong — pass the complete header value including the
scheme, Bearer <token>, not <token> — or the access token minted for the run
has expired. With oauth2_client_credentials, the access token obtained at
launch has expired. Albus refreshes neither token during a run. Details in
Authenticate Albus to your MCP server. Separately,
confirm the server speaks Streamable HTTP at the URL you gave; stdio servers
cannot be reached.
Installation
albus: command not found right after installing
The install directory is not on PATH — usually ~/.local/bin. Open a new
shell, or add it.
need uv, pip, or conda on PATH
The installer found no Python package manager. Install uv
(curl -LsSf https://astral.sh/uv/install.sh | sh) and run it again.
could not use <path>/credentials.json
The config directory is read-only or owned by another user — ordinary where agents
run. Fix its permissions, or point ALBUS_CONFIG_DIR at a writable directory. An
exported ALBUS_API_KEY avoids the disk entirely.
Still stuck
Collectalbus status, the session id, the run’s invocation_key, and
albus sessions audit <session-id>, then email
carlo@albus.sh. Never include a key or secret value.