base44-troubleshooter

本番環境の問題をトラブルシューティングする

前提条件

ログを取得する前に、認証を確認してください。

npx base44 whoami

認証されていない場合、またはトークンの有効期限が切れている場合は、npx base44 login を実行するようユーザーに案内してください。

次のいずれかの方法でアプリのコンテキストを解決してください。

# From a linked local project
cat base44/.app.jsonc

# Or explicitly
npx base44 logs --app-id app_123

利用可能なコマンド

コマンド	説明	リファレンス
base44 logs	このアプリの関数ログを取得します	project-logs.md
base44 workflows runs	ワークフローの実行を新しい順に一覧表示します。失敗した実行には、失敗したタスクとその根本的なエラーが含まれます	workflows-runs.md
base44 workflows list	このアプリのワークフローをステータスと実行概要とともに一覧表示します	workflows-list.md

ログは書き込み直後に読み取れるとは限りません

1 回取得して実行結果が見つからなくても、何も証明されません。 1 回限りの base44 logs は、呼び出しより更新が遅れるインデックスを読み取るため、関数の実行直後に結果が空でも、それは想定どおりであり、問題の証拠ではありません。

• リアルタイムでデバッグする場合は、--follow を使用してください。 リアルタイムストリームが利用可能な場合、1 秒未満で行が届きます。利用できない場合、CLI がその旨を伝え、代わりにポーリングします（Warning: Realtime logs are not available for this app — falling back to polling (lines may lag ~20-30s).）。どちらの場合も、--follow が適切なツールです。選択に迷う必要はありません。
• 1 回限りの取得には約 20～30 秒の遅れがあります。 これは取り込みにかかる時間であり、フィルターの問題ではありません。
• 出力が空の場合、変更すべきなのは時間であり、フラグではありません。 待ってから、同じコマンドをもう一度実行してください。--limit の値を増やしたり、--level を外したり、--order を切り替えたりしても、まだ取り込まれていない行には何の影響もありません。フラグをあれこれ変えると、エージェントが誤った診断をしてしまいます。

トラブルシューティングの流れ

1. 発生状況を確認する — --follow

障害を再現できる場合（または障害が現在発生中の場合）は、事後にログを取得するのではなく、ここから始めてください。

npx base44 logs --follow
npx base44 logs --follow --function <function_name>

次に関数を呼び出し、届いた内容を確認します。正常なストリームを誤って読み取らないためのルールは次のとおりです。

• 時間を決めて判断しないでください。 ストリームを開き、関数を呼び出して、行が表示されるまで読み続けてください。一定の時間だけ待って出力し、「壊れている」と結論付けてはいけません。ストリームが静かなのは、何も呼び出されていないためです。
• 配信は行単位ではなく、呼び出し単位です。 実行時間の長い関数の行は、呼び出しが終了したときにすべて届きます。呼び出しの途中で何も表示されないのは正常です。
• フォロー中に再デプロイしても問題ありません。 デプロイすると数秒でスクリプトが切り替わり、同じストリームが次回の呼び出し時に新しいコードの行を配信します。デプロイのたびにストリームを終了して作り直す必要はありません。
• --follow では --since は拒否されます（ストリームは現在から開始します）。--until と --order も同様です。過去のログには、1 回限りの取得を使用してください。
• モードは起動時に一度だけ決まります。 最初の接続が拒否されるか到達不能の場合、実行中はずっとポーリングします。ストリームが開いた場合、ポーリングへのフォールバックはありません。
• 実行中にストリームが切断されると、コマンドは終了し、 Error: The realtime log stream stopped and could not be re-established が表示され、終了コード 1 が返されます。この終了はストリームが再接続を断念したことを示すものであり、ログ機能が壊れている証拠ではありません。フラグを変更せず、同じコマンドを再実行してください。

2. リクエストではなく、スケジュールされた実行かどうかを確認します

ワークフローは自動化システムです。cron スケジュール、エンティティのトリガー、コネクターのイベント、アプリ内のエージェントアクションなどが含まれます。「スケジュールされたジョブが実行されなかった」や「自動化が動かなくなった」という問題では、関数ログは適切なツールではありません。 関数が出力した内容は確認できますが、実行がディスパッチされたかどうか、実行内のどのタスクが失敗したか、ワークフローが発火しなくなった理由まではわかりません。

npx base44 workflows runs --status failed
npx base44 workflows list

失敗した実行には、失敗したタスクとその根本原因となるエラーが記録されています。まずはそこを確認し、失敗したタスクが呼び出した関数がわかってから base44 logs を調べてください。workflows list には consecutiveFailures が表示されます。ゼロを超えているワークフローは、対応が必要です。

ここで誤解を招きやすい点が2つあります。

• トリガー列の manual は、人が何かをクリックしたという意味ではありません。 トリガータイプなしでディスパッチされた実行に付けられる表示です。
• テスト実行も含まれます。トリガータイプの横に (scheduled, test) と表示されます。何かを確認するために自分で実行したものも、一覧に表示されます。

3. 最近のエラーを確認します

まず、すべての関数の最新のエラーを取得します。

npx base44 logs --level error

4. 特定の関数を詳しく調べます

失敗している関数がわかっている場合は、次のようにします。

npx base44 logs --function <function_name> --level error

プロジェクトディレクトリの外にいる場合は、アプリを明示的に指定してください。

npx base44 logs --app-id app_123 --function <function_name> --level error

--function フィルターは、関数名が記録された行に対するフィルターです。従来の関数単位のデプロイを使用しているアプリでは、関数名が記録されない行が出力されるため、フィルターを適用するとそれらが表示されないことがあります。この問題は、アプリの次回のデプロイで自動的に解消されます。フィルター適用後の結果が空の場合は、ログがないと結論付ける前に、--function を指定せずに再実行してください。

5. 期間を指定して調べます

ユーザーから報告された問題のタイムスタンプと照合します。

npx base44 logs --function <function_name> --since <start_time> --until <end_time>

6. ログを分析します

• 出力のスタックトレースとエラーメッセージを確認します
• タイムスタンプを確認し、ユーザーから報告された問題と照合します
• さらに過去まで確認するには、--limit を明示的に指定します。デフォルトのページサイズはなく、500を超える値は500に制限されます

結果が空の場合

No logs found matching the filters. は曖昧なメッセージです。「問題なし」と受け取ってはいけません。次のいずれかを意味します。

• 実行がまだ取り込まれていない（最も一般的です。上記を参照し、しばらく待ってから再実行してください）
• 該当する名前の関数が存在しない、またはフィルターによって関数名が記録されていない行が除外された（ステップ3を参照）
• --env prod を指定してログを確認しているが、アプリが公開されていない (No production logs found. と表示されます。ドラフトのログを確認するには --env preview を試してください)