トラブルシューティング
Busabase でよくあるエラーの意味と直し方 — Cloud とローカル Desktop の両方、CLI・curl・エージェントから。
トラブルシューティング
ほとんどのエラーは 2 つの問いに集約されます：どのホストと話しているか、そしてそのホストで認証できているか。このページでは（busabase-cli・curl・エージェントで）目にするエラーを具体的な対処に対応づけます。
まず：どのホストか、どう選ばれるか
| Cloud | ローカル / Desktop | |
|---|---|---|
| ベース URL | https://busabase.com | http://localhost:15419 |
| 認証 | API キー必須（Bearer トークン） | なし — 自分のマシン上で開かれている |
| 起動が必要 | 常時稼働 | Desktop アプリ、または npx busabase server |
CLI と API はホストとキーをこの順で解決します：
- 明示フラグ —
--base-url/--api-key - 環境変数 —
BUSABASE_BASE_URL/BUSABASE_API_KEY - 保存済み設定 —
~/.busabase/.env（エージェントのオンボーディングで書き込まれる。読み込むにはset -a; . ~/.busabase/.env; set +a） - デフォルト —
https://busabase.com（Cloud）
設定なしの busabase-cli は Cloud と話します — つまりキーを足すまで素の bases list は 401 になります。ローカルサーバーに向けたい場合は --base-url http://localhost:15419（または BUSABASE_BASE_URL を設定）。
よくあるエラー
「Could not reach <host>」/ 接続拒否 / fetch failed
ホストが応答していません。
- Cloud — インターネット接続と、URL が
https://busabase.comであることを確認。 - ローカル — サーバーが起動していません。Desktop アプリを起動するか
npx busabase serverを実行（http://localhost:15419で待ち受け）し、--base-url http://localhost:15419またはexport BUSABASE_BASE_URL=http://localhost:15419で CLI を向けます。
401 Unauthorized
ホストが有効な API キーを必要としているのに受け取っていません。
- キーを作成：ダッシュボード → 設定 → API トークン（一度だけ表示 — コピーしておく）。
- 渡し方：
--api-key <token>、export BUSABASE_API_KEY=…、または~/.busabase/.envに保存。 - ローカルサーバー（キー不要）のつもりなら、既定で Cloud に当たっている可能性が高いので
--base-url http://localhost:15419を追加。
403 Forbidden
認証はできたが、このスペース／リソースには許可されていません。キーが正しい組織／スペースに属しているか、必要な権限があるかを確認。特定のスペースを指定するには x-busabase-space: <id> ヘッダーを追加。
404 Not found
Base・レコード・変更リクエストの id が存在しない（またはキーから見えない）。古い id を使い回さず、一覧で現在の id を取得（busabase-cli bases list、… change-requests list）。
409 Conflict
状態が変わりました — 例：古い baseContentHash、すでにマージ済みの変更リクエスト。現在の状態を読み直してから一度だけ再試行。
422 ルール違反
リクエストは理解されたがルールに反します — 最も多いのはまだ承認されていない変更リクエストをマージしようとしたケース。提案 → レビュー（承認）→ マージの順を守る。レビューを飛ばさない。
429 レート制限
リクエストが多すぎます。少し待ってから再試行。
5xx サーバーエラー
サーバー側の問題。短い間隔を空けて最大 2 回まで再試行。続く場合は発生時刻と実行内容を記録。
2xx 以外では API は error.message を含む JSON を返します — そのまま読んでください。たいてい問題のフィールドやルールを正確に示しています。
設定リファレンス
| 何を | フラグ | 環境変数 | 保存先 |
|---|---|---|---|
| ホスト | --base-url <url> | BUSABASE_BASE_URL | ~/.busabase/.env |
| API キー（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