エラーコード

CLI とデプロイのエラーは code と hint(対処方法)を伴って返ります。AI エージェントにそのまま渡せば対処できます。hint がある場合はこのページより hint を優先してください。workspace 名のコードへ移行したエラーでは、旧 tenant 名のコードを互換用の error.aliases に載せます。撤去時期は未定です。ここでは人が読むための一覧を、発生する場所ごとにまとめます。

このページは日常的に遭遇するコードの一覧で、全コードの網羅ではありません。掲載していないコードが出たときも、code と hint の形は同じです。

エラーがどこに入っているか

経路によって、理由を読む場所が違います。

経路	形
CLI(--json)	標準出力に {"error":{"code","message","hint","retryable"}}
デプロイの失敗(status / diagnose)	failure_code と hint
Keelson API の通常のエラー	{"detail": "..."}。入力検証エラーでは detail が配列。code / hint は付かない
アプリの URL に対する認可の拒否(ゲートウェイ)	ブラウザには HTML の案内。fetch / XHR には {"detail":"ip-restricted"} のような JSON と、理由を入れた X-Keelson-Auth-Error ヘッダー
稼働枠不足・停止中(ゲートウェイ)	503。x-keelson-platform-error ヘッダー(capacity-full / app-suspended)。稼働枠不足は X-Keelson-Error-Code: CAPACITY_FULL も付く
存在しない URL・停止中・予約パス(エッジ)	404 / 410 / 503 / 403 の平文と x-keelson-platform-error ヘッダー。ゲートウェイに届かないので X-Keelson-Auth-Error は付かない
Files / Media の配信	x-keelson-error ヘッダーに理由。一部のコードだけ {error, hint, doc} の JSON

retryable は HTTP のステータスからは決められません。同じ 503 でも false のことがあり、ビルドの 429 にはトライアルの累積上限のように待っても解除されないものがあります。

デプロイ前のチェック(CLI)

アップロード前に報告され、keelson deploy --check でも確認できます。エラーはデプロイを止めますが、警告は止めません。依存マニフェストがない場合、Go ではエラー、Python と Node.js では警告になります。

コード	原因	対処
missing_dependency_manifest	選択したランタイムの依存マニフェストがない	Go ではプロジェクトルートに go.mod を置く。Python または Node.js で外部ライブラリを使う場合はマニフェストを置く。標準ライブラリだけのアプリでは依存マニフェストは必須ではありません
command_installs_dependencies	command に pip install / npm install / go build がある	削除し、起動コマンドだけにする
runtime_command_mismatch	runtime と command の言語が合わない(例: python-slim で node)	どちらかを直す
assets_dir_empty	assets.dir が無い、空、またはパスの大文字小文字が違う	ビルドを実行する。パスを確認する
assets_fallback_missing	assets.fallback のファイルが assets.dir にない	ビルド出力を確認する
db_wiring_fail(警告)	db.mode とコードの DB 接続が食い違う(接続先、ローカル開発用のフォールバック、宣言の不一致など複数の規則がある)	表示された hint に従う。多くは KEELSON_DB_URL を読む libSQL クライアントに直す
file_wiring_fail(警告)	状態ファイルやアップロードをローカルディスクに書いている	Files / Media SDK に置き換える

keelson.yaml の検証

コード	原因	対処
invalid_keelson_config	YAML が不正、db.mode が libsql / none 以外、db.migrate を none と併用、KEELSON_ で始まる env、/__keelson 配下のパス、不明な runtime、cron が 10 本超、など	message の内容を直す
config_missing_field	必須フィールドがない(slug、runtime、db など。静的サイトでは type と assets も)	追加する
env_value_not_string	env の値が文字列でない、YAML が曖昧に解釈するキー、キーの重複、merge key(<<)	値は引用符かブロック文字列にする。曖昧なキー(on / yes / 数字など)は引用符で囲む。重複は削除する。merge key は展開して書く。重複と merge key は引用符で囲んでも拒否される
description_too_long	description が 300 文字超	短くする
workers_not_supported	workers: がある	削除して crons で書く
DB_DATABASES_REMOVED	databases: がある	削除する。永続データは db.mode: libsql
SQLITE_LOCAL_SQLITE_INVALID_PATH	db.local_sqlite.paths が /tmp/ の外	/tmp/ か :memory: にする
CRON_TIMEOUT_EXCEEDS_STANDARD_LIMIT	crons[].timeout が 600 秒超	下げる、処理を分割する
plan_cron_limit / plan_cron_min_interval / plan_schedule_timeout	cron の本数・間隔・timeout がプラン上限を超える	減らすか、プランを上げる
ARTIFACT_SQLITE_FILE_DRIVER	ファイル SQLite クライアント(sqlite3、better-sqlite3 など)が検出された	libSQL クライアントへ移行。一時用途なら db.local_sqlite で宣言
ARTIFACT_EXEC_NODE_CRON / ARTIFACT_EXEC_APSCHEDULER / ARTIFACT_EXEC_BACKGROUND_TASKS / ARTIFACT_EXEC_SET_INTERVAL(注意)	アプリ内スケジューラが検出された	crons に移す

ビルド出力の直下に __keelson ディレクトリがあるとビルドが失敗します。このときの failure_code は deploy.build.failed で、ビルドログに reserved_path_conflict が出ます。ディレクトリ名を変えてください。

デプロイの失敗

keelson status / keelson diagnose に failure_code として表示されます。

コード	原因	対処
deploy.config.invalid	keelson.yaml の内容が不正	指摘されたキーを直して再デプロイ
deploy.config.secret_missing	secrets.required で宣言したシークレットが未設定	keelson secrets set <KEY>(値は標準入力)で全て設定してから再デプロイ
deploy.artifact.invalid	アーカイブの問題(ロックファイルなし、ブロック対象の検出)	指摘された箇所を直す
deploy.artifact.assets_invalid	assets.dir / assets.fallback で宣言したファイルがアップロードに含まれていない	手元でビルドしてから再デプロイ
deploy.build.failed	ビルド失敗(依存の解決失敗、ビルドスクリプトのエラー、予約パスの衝突)	keelson logs deploy <deploy_id> でビルド出力の末尾を見る
deploy.build.timed_out	ビルドが制限時間内に終わらなかった	不要な依存を減らす、重い前処理をビルドの外に出す
deploy.build.image_too_large	イメージが大きすぎる	不要な依存やファイルを減らす
deploy.runtime.start_failed	アプリが起動中に終了、またはコンテナが起動状態にならなかった	keelson logs deploy <deploy_id> で保存済みのアプリの起動ログを読み、PORT と 0.0.0.0 を確認
deploy.runtime.health_check_failed	起動・ヘルス検証の制限時間内に、/(もしくは health.path)から期待する応答(2xx / 3xx / 404)を得られなかった。アプリが起動中に終了した場合や、401 / 403 / 5xx を返し続ける場合を含む	keelson logs deploy <deploy_id> で保存済みのアプリの起動ログを読み、待ち受けポートと health.path を確認
deploy.runtime.migration_failed	db.migrate が 0 以外で終了。旧リビジョンが配信を継続	マイグレーションを直して再デプロイ。途中まで適用された DB の変更は自動では戻らない
deploy.verify.failed	verify のパスが取得できない、または JS / CSS の Content-Type が不一致	パスとビルド出力を確認。詳細は failure_logs の verification_* コードに出る
deploy.plan.limit_exceeded	プランの上限超過	減らすか、プランを上げる
deploy.plan.cron_count_exceeded	cron の本数がプラン上限を超えている	減らすか、プランを上げる
deploy.plan.cron_interval_too_short	cron の間隔がプランの最小間隔より短い	間隔を伸ばすか、プランを上げる
deploy.plan.schedule_timeout_exceeded	明示した crons[].timeout がプラン上限を超えている	timeout を下げるか、プランを上げる
deploy.app.suspended	アプリまたはワークスペースが Keelson 側の制限措置を受けている	サポートへ連絡する。利用者や管理者による再開では解除されない
deploy.app.operation_in_progress	このアプリで別の操作が進行中だったため、デプロイを開始できなかった	別の操作が完了してから再デプロイ
deploy.platform.temporarily_unavailable	一時的な障害	待ってから再試行する。追加で 3 回まで。それでも失敗するなら deploy_id を添えてサポートへ
deploy.platform.error	プラットフォーム側のエラー	再試行しても直らない。deploy_id を添えてサポートへ
deploy.cancelled	デプロイが取り消された	必要なら再デプロイ
deploy_in_progress(409)	別のデプロイまたはアプリ操作が進行中	進行中の操作が完了してから同じコマンドを再実行
build_rate_limit_exceeded / build_guardrail_exceeded(429)	ビルド回数・ビルド時間・同時実行・連続失敗の上限	メッセージが解除条件を示す。連続失敗は原因を直して記載の時刻を待つ。トライアルのビルド枠は累積で、待っても解除されないので、その場合はプランを変更する
saved_config_unsupported(409)	再デプロイ / ロールバック対象の keelson.yaml が現在のスキーマに合わない	直して通常のデプロイをする

定期実行ジョブの失敗

keelson crons runs list と keelson logs cron に出ます。

コード	意味
cron.failed.command_failed	コマンドが 0 以外で終了した
cron.failed.timed_out	timeout を超えた
cron.failed.terminated_no_callback	実行が終了したが結果が報告されなかった
dispatch_failed	実行の起動に失敗した
cron.skipped.schedule_disabled	ジョブが無効化されている
cron.skipped.quota_exceeded	プランの実行枠を超えた
cron.skipped.due_to_lock / cron.skipped.lease_held	前回の実行がまだ終わっていない
cron.skipped.missed_run	予定時刻を過ぎたため飛ばした
cron.skipped.app_suspended	アプリが停止中
cron.skipped.plan_downgrade	プラン変更で実行できなくなった

バックアップと復元

keelson snapshots ... のエラーです。名前が snapshot_export_ で始まるものは snapshots export の同じ条件です。

コード	意味	対処
snapshot_plan_not_included	手動スナップショットがプランに含まれない	プランを変更する
snapshot_no_managed_db	Managed SQLite を使っていない	db.mode: libsql で DB を作ってから
snapshot_db_name_invalid / snapshot_db_name_unknown	DB 名が不正、または存在しない	hint に出る名前を使う
snapshot_already_running / snapshot_export_already_running	前の処理が実行中	終わってから再試行
snapshot_rate_limited / snapshot_export_rate_limited	回数上限	hint の時刻まで待つ
snapshot_export_invalid_timestamp	復元可能な範囲の外の時刻	範囲内の時刻を指定する
snapshot_app_deleting / snapshot_export_app_deleting	アプリが削除中	—
snapshot_launch_failed / snapshot_export_launch_failed	起動に失敗	再試行。続くならサポートへ
snapshot_disabled / snapshot_storage_unconfigured(export 系も同様)	プラットフォーム側で無効	サポートへ
snapshot_not_ready	まだダウンロードできない(X-Keelson-Error-Code ヘッダー)	完了を待つ

CLI のエラー

コード	意味	対処
not_logged_in	未ログイン	keelson login
multiple_workspaces / workspace_ambiguous / workspace_not_found / no_workspaces	ワークスペースを特定できない	--workspace <slug>。keelson workspaces list --query で検索
app_not_found	アプリが見つからない	slug を確認。新規なら --new
app_manage_required	アプリは存在するが、管理権限がない	現在の管理者に、管理権限を持つグループへ自分を追加してもらう。ワークスペースの OWNER / ADMIN なら keelson groups members add <グループ> <メール> で自分を追加する
app_deleting	削除中のアプリ	完了を待つ
forbidden	権限がない。CONSOLE_ONLY_OPERATION ならコンソール限定の操作	ロール・アプリ権限を確認
confirmation_required	ブラウザでの承認が必要な操作	表示された URL を開いて承認。削除・SQL・復元は承認と同時に実行されるので再実行は不要。preview / app curl は承認後に --confirmation <id> を付けて同じコマンドを再実行する
confirmation_expired / confirmation_rejected	承認の期限切れ(削除・SQL・復元は 15 分、preview / app curl は 30 分)/ 却下	コマンドをやり直す
deploy_failed	デプロイ失敗	keelson diagnose <deploy_id>
sql_failed	db apply の SQL エラー。ロールバック済み	SQL を直す
usage(access set。API の 409 detail.reason が last_manage_binding_removed / no_effective_manager / self_lockout)	管理グループが空になる、有効な管理者がいなくなる、自分の権限が失われる	管理グループを残す。--allow-self-lockout で解除できるのは自分が外れる場合だけで、管理グループや有効な管理者がゼロになる変更は解除できない
transient	一時的なネットワークエラー	--retry を付けて再試行
skill_outdated(meta.skill_outdated。doctor の警告でもある)	Skill が CLI より古い。コマンドは失敗しない	keelson install-agent --yes

利用者がブラウザで見るもの

表示	状態	対処
ログイン画面	未ログイン	ワークスペースに登録されたアカウントでログイン
「アクセスできません」(403)	メンバーでない、ブロック済み、アプリの閲覧権限がない	管理者にメンバー登録・権限を依頼
「このアプリは、許可されたアクセス元からのみ利用できます」(403)	IP 制御で拒否。画面に送信元 IP が表示される	管理者にその IP のアクセス元への追加を依頼
「アプリの稼働枠が空いていないため起動できません」(503)	同時に使えるアプリ数の上限	枠を使っている別のアプリへのアクセスが約 5 分途絶えると空く。使われ続けていれば空かないので、管理者がアプリの停止・優先起動・プラン変更で調整する
「アプリを起動しています」	スリープからの起動中	数秒待つ(自動で再読み込み)
「このアプリは停止中です」(503)	サスペンド中、または Keelson 側の制限措置	管理者が再開する。再開しても直らない場合は制限措置なのでサポートへ
「App not found」(404)	URL が間違っている、またはアプリが削除された	URL を確認
410 Gone	公開 URL が変更された(旧 URL は 30 日間予約)	新しい URL を案内
504	アプリが 120 秒以内に応答ヘッダーを返し始めなかった。ストリーミングの全体時間ではない	処理を短くする、cron に逃がす
501	WebSocket は未対応	SSE やポーリングに変える

API や XHR から同じ状況になると、ゲートウェイの拒否では JSON の detail と X-Keelson-Auth-Error ヘッダーに理由(ip-restricted、app-view-denied など)が入ります。稼働枠不足と停止中は x-keelson-platform-error ヘッダー(capacity-full、app-suspended)です。

外部連携(アプリトークン / Webhook)

詳しい理由は X-Keelson-Auth-Error で返ります。IP 許可範囲による拒否でも、互換性のため JSON の detail は machine-forbidden または webhook-forbidden のままです。

machine-forbidden と webhook-forbidden は、アプリが存在しない場合、トークンが別のアプリのものである場合、経路が消失した場合を意図的にまとめ、応答からアプリの存在を判定できないようにしています。

X-Keelson-Auth-Error	原因
invalid-app-token	トークンが無効、または失効済み
machine-scope-denied	トークンのスコープ(api / webhook)がパスと合わない
machine-endpoint-denied	auth.endpoints で宣言されていないパス・メソッド
machine-forbidden / webhook-forbidden	アプリが存在しない、トークンが別のアプリのもの、または経路が消失した
machine-ip-not-allowed	アプリトークンの許可 IP の外から呼ばれた
invalid-webhook-secret	Webhook シークレットが一致しない
webhook-scope-denied	トークンに webhook スコープがない
webhook-ip-not-allowed	Webhook トークンの許可 IP の外から呼ばれた

/api/webhooks/email などプラットフォーム予約のパスへの Webhook は、ゲートウェイより手前のエッジが 403 の平文で拒否します。このときのヘッダーは X-Keelson-Auth-Error ではなく x-keelson-platform-error: auth-webhook-endpoint-blocked です。