常见 Busabase 报错分别是什么意思、怎么解决——无论是 Cloud 还是本地 Desktop，通过 CLI、curl，还是任意智能体。

故障排查

大多数报错最终都归结到两个问题：我在跟哪个 host 通信，以及我对它是否已认证。这个页面把你在 busabase-cli、curl 或智能体里会遇到的报错，对应到具体的解决办法。

首先：是哪个 host，怎么选出来的？

	Cloud	本地 / Desktop
Base URL	`https://busabase.com`	`http://localhost:15419`
认证	必须提供 API key（Bearer token）	无需认证——在你自己机器上开放访问
必须保持运行	始终在线	Desktop 应用或 `npx busabase server`

CLI 和 API 按以下顺序解析 host 和 key：

显式传入的参数——--base-url / --api-key
环境变量——BUSABASE_BASE_URL / BUSABASE_API_KEY
保存的配置——~/.busabase/.env（智能体接入时写入；用 source 加载：set -a; . ~/.busabase/.env; set +a）
默认值——https://busabase.com（Cloud）

一个没有任何配置的全新 busabase-cli 默认连的是 Cloud——所以一个裸的 bases list 会返回 401，直到你添加 key 为止。想连本地服务器？加上 --base-url http://localhost:15419（或设置 BUSABASE_BASE_URL）。

常见报错

"Could not reach <host>" / 连接被拒绝 / `fetch failed`

host 没有响应。

Cloud——检查你的网络连接，确认 URL 是 https://busabase.com。
本地——服务器没有在运行。启动 Desktop 应用，或者运行 npx busabase server（它监听 http://localhost:15419），然后用 --base-url http://localhost:15419 或 export BUSABASE_BASE_URL=http://localhost:15419 指向它。

401 Unauthorized

这个 host 需要一个有效的 API key，但没收到。

创建一个 key：Dashboard → Settings → API 令牌（只显示一次——记得复制）。
提供它：--api-key <token>，或者 export BUSABASE_API_KEY=…，或者保存到 ~/.busabase/.env。
如果你本来想连的是本地服务器（不需要 key），那你很可能默认连到了 Cloud——加上 --base-url http://localhost:15419。

403 Forbidden

已经通过认证，但对这个空间或资源没有权限。确认这个 key 属于正确的组织/空间，并且拥有所需的权限。要指定某个具体空间，加上 x-busabase-space: <id> 请求头。

404 Not found

对应的 Base、记录，或变更请求 id 不存在（或者你的 key 看不到它）。重新列一遍拿到最新的 id（busabase-cli bases list、… change-requests list），不要复用一个过期的 id。

409 Conflict

状态在你操作期间被改变了——比如 baseContentHash 已经过期，或者变更请求已经被合并了。重新读取最新状态，再重试一次。

422 违反了某条规则

请求本身能被理解，但违反了某条规则——最常见的是合并一个还没被批准的变更请求。请按顺序来：提出 → 审核（批准）→ 合并。永远不要绕过审核。

429 Rate limited

请求太频繁了。降低频率后重试。

5xx Server error

服务器端出了问题。用短暂的退避间隔重试最多两次；如果依然持续，记下时间和你当时执行的操作。

任何非 2xx 响应，API 都会返回带 error.message 的 JSON——照原文读一遍，它通常会直接指出具体是哪个字段或哪条规则出了问题。

配置参考

内容	参数	环境变量	保存位置
Host	`--base-url <url>`	`BUSABASE_BASE_URL`	`~/.busabase/.env`
API key（Cloud）	`--api-key <token>`	`BUSABASE_API_KEY`	`~/.busabase/.env`

busabase-cli 会自动加载 ~/.busabase/.env，所以不需要手动 source 什么；下面的 source 步骤只有直接用 curl 时才需要。

# 查看 / 加载已保存的配置
cat ~/.busabase/.env
set -a; . ~/.busabase/.env; set +a   # 只有 curl 需要——CLI 会自己读这个文件

# 确认连接是否正常
busabase-cli whoami        # 当前是谁 + 在哪个空间
busabase-cli bases list    # 能不能读到数据？

另请参阅：接入你自己的智能体 · API 令牌 · REST API · MCP

故障排查

On this page