Troubleshooting
What the common Busabase errors mean and how to fix them — for both Cloud and local Desktop, over the CLI, curl, or any agent.
Troubleshooting
Most errors come down to two questions: which host am I talking to, and am I authenticated for it. This page maps the errors you'll see (in busabase-cli, curl, or your agent) to a concrete fix.
First: which host, and how is it chosen?
| Cloud | Local / Desktop | |
|---|---|---|
| Base URL | https://busabase.com | http://localhost:15419 |
| Auth | API key required (Bearer token) | none — open on your machine |
| Must be running | always on | the Desktop app or npx busabase server |
The CLI and API resolve the host and key in this order:
- an explicit flag —
--base-url/--api-key - environment —
BUSABASE_BASE_URL/BUSABASE_API_KEY - your saved config —
~/.busabase/.env(written during agent onboarding;sourceit to load:set -a; . ~/.busabase/.env; set +a) - the default —
https://busabase.com(Cloud)
A fresh busabase-cli with no config talks to Cloud — so a bare bases list returns 401 until you add a key. Talking to a local server instead? Pass --base-url http://localhost:15419 (or set BUSABASE_BASE_URL).
Common errors
"Could not reach <host>" / connection refused / fetch failed
The host isn't answering.
- Cloud — check your internet connection and that the URL is
https://busabase.com. - Local — the server isn't running. Start the Desktop app, or run
npx busabase server(it listens onhttp://localhost:15419), then point the CLI with--base-url http://localhost:15419orexport BUSABASE_BASE_URL=http://localhost:15419.
401 Unauthorized
The host needs a valid API key and didn't get one.
- Create a key: Dashboard → Settings → API Tokens (shown once — copy it).
- Provide it:
--api-key <token>, orexport BUSABASE_API_KEY=…, or save it in~/.busabase/.env. - If you meant a local server (which needs no key), you're probably hitting Cloud by default — add
--base-url http://localhost:15419.
403 Forbidden
Authenticated, but not allowed for this space or resource. Confirm the key belongs to the right organization/space, and that it has the needed permission. To target a specific space, add the x-busabase-space: <id> header.
404 Not found
The Base, record, or change request id doesn't exist (or isn't visible to your key). Re-list to get a current id (busabase-cli bases list, … change-requests list) rather than reusing a stale one.
409 Conflict
State moved under you — e.g. a stale baseContentHash, or a change request already merged. Re-read the current state, then retry once.
422 A rule was violated
The request was understood but breaks a rule — most often merging a change request that isn't approved yet. Follow the order: propose → review (approve) → merge. Never bypass review.
429 Rate limited
Too many requests. Back off, then retry.
5xx Server error
A problem on the server. Retry up to twice with a short backoff; if it persists, note the time and what you ran.
On any non-2xx the API returns JSON with an error.message — read it verbatim; it usually names the exact field or rule at fault.
Configuration reference
| What | Flag | Env var | Saved in |
|---|---|---|---|
| Host | --base-url <url> | BUSABASE_BASE_URL | ~/.busabase/.env |
| API key (Cloud) | --api-key <token> | BUSABASE_API_KEY | ~/.busabase/.env |
busabase-cli auto-loads ~/.busabase/.env, so it works without sourcing anything; the source step below is only needed for raw curl.
# Inspect / load your saved config
cat ~/.busabase/.env
set -a; . ~/.busabase/.env; set +a # only needed for curl — the CLI reads the file itself
# Verify you're connected
busabase-cli whoami # who + which space
busabase-cli bases list # can you read data?See also: Bring Your Own Agent · API Tokens · REST API · MCP