frappe-agent-debugger

Frappe デバッグエージェント

エラーを分類し、関連するコードを特定して、対象を絞った診断チェックリストを適用することで、Frappe/ERPNext の問題を体系的に診断します。

目的：試行錯誤によるデバッグをなくし、決定論的な診断ワークフローに従います。

このエージェントを使用する場面

ERROR ANALYSIS TRIGGER
|
+-- Python traceback or error message
|   "ImportError: cannot import name X from frappe"
|   --> USE THIS AGENT
|
+-- JavaScript console error
|   "Uncaught TypeError: frm.set_value is not a function"
|   --> USE THIS AGENT
|
+-- Silent failure (no error, wrong behavior)
|   "Server Script runs but nothing happens"
|   --> USE THIS AGENT
|
+-- Scheduler/background job failure
|   "Job X failed" in scheduler logs
|   --> USE THIS AGENT
|
+-- Build/asset errors
|   "Module not found" or blank page after build
|   --> USE THIS AGENT

デバッグワークフロー

STEP 1: CLASSIFY ERROR TYPE
  Python | JavaScript | Database | Permission | Hook | Scheduler | Build

STEP 2: IDENTIFY THE MECHANISM
  Controller | Server Script | Client Script | Hook | Scheduler | API

STEP 3: LOCATE RELEVANT CODE
  Use Frappe file path conventions to find source

STEP 4: APPLY DIAGNOSIS CHECKLIST
  Run type-specific checklist for the error class

STEP 5: SUGGEST FIX
  Provide corrected code + reference relevant frappe-* skills

詳細な手順については、references/workflow.md を参照してください。

ステップ 1：エラーの分類

エラーの種類	判断材料	主なツール
Python	.py ファイルを含むトレースバック	bench console、ログ
JavaScript	ブラウザーコンソールのエラー、cur_frm の問題	ブラウザーの DevTools
データベース	OperationalError、IntegrityError	bench mariadb
権限	frappe.PermissionError、403 レスポンス	Permission Inspector
フック	bench migrate 後のエラー、誤ったイベント	bench doctor
スケジューラー	bench doctor の警告、RQ の失敗	スケジューラーログ
ビルド	アセットの不足、空白ページ、モジュールのエラー	bench build --verbose

ステップ 2：仕組みの特定

症状	考えられる仕組み
フォームの保存／送信中にエラーが発生する	コントローラーまたは Server Script（validate/on_submit）
ページの読み込み時にエラーが発生する	Client Script または Web Template
API 呼び出しからエラーメッセージが返される	ホワイトリスト登録されたメソッドまたは REST API ハンドラー
バックグラウンドでエラーが発生する	スケジューラーイベントまたは frappe.enqueue() ジョブ
bench migrate 後にエラーが発生する	フックの設定またはパッチ
bench build 後にエラーが発生する	フロントエンドのアセットパイプライン

ステップ 3：ファイルパスの規則

仕組みに応じて、必ず以下の場所を確認してください。

仕組み	ファイルパスのパターン
コントローラー	apps/{app}/{app}/{module}/{doctype}/{doctype}.py
Server Script	Desk > Server Script list（データベースに保存）
Client Script	Desk > Client Script list（データベースに保存）
hooks.py	apps/{app}/{app}/hooks.py
スケジューラー	apps/{app}/{app}/tasks.py または hooks.py の scheduler_events
ホワイトリスト登録	apps/{app}/{app}/{module}/*.py（@frappe.whitelist を検索）
Jinja	apps/{app}/{app}/templates/
パッチ	apps/{app}/{app}/patches/

ステップ 4：診断チェックリスト（クイックリファレンス）

Python のエラー

エラーパターン	考えられる原因	修正方法
AttributeError: 'NoneType'	frappe.get_doc() が None を返した	まずドキュメントが存在するか確認する
ValidationError	validate 内の frappe.throw()	メッセージを読む — それが診断結果です
ImportError	インポートパスの誤り、またはインポートを使用する Server Script	Server Script ではインポートできません
LinkValidationError	参照先のドキュメントが存在しない	Link フィールドの参照先が存在するか確認する
TimestampMismatchError	同時編集の競合	保存前にドキュメントを再読み込みする
DuplicateEntryException	一意制約違反	命名規則または一意フィールドを確認する
MandatoryError	必須フィールドが空	保存／送信前にフィールドを設定する
InvalidStatusError	docstatus の遷移が不正	0→1→2 の順序に従う
CircularLinkingError	親子関係が自己参照している	ドキュメント階層を修正する

JavaScript のエラー

エラーパターン	考えられる原因	修正方法
frm.X is not a function	API の誤り、または古いコード	キャッシュをクリアし、API 名を確認する
cur_frm is undefined	フォームのコンテキスト外でコードが実行されている	ハンドラーパラメーターから frm を使用する
Uncaught Promise	frappe.call に async/await がない	コールバックを追加するか、await を使う
frm.doc 内の field undefined	DocType にフィールドが存在しない	fieldname のスペルを確認する
フォームが更新されない	frm.refresh_fields() がない	set_value の後に更新を追加する

データベースエラー

エラーパターン	考えられる原因	修正方法
OperationalError: 1054	カラムが存在しません	bench migrate を実行します
OperationalError: 1146	テーブルが存在しません	bench migrate を実行します
IntegrityError: 1062	主キーが重複しています	命名／autoname を確認します
IntegrityError: 1452	外部キー制約違反です	リンク先のドキュメントが存在しません
OperationalError: 1213	デッドロックです	トランザクションの範囲を縮小します
InternalError: 1366	文字セットに対応しない文字です	入力のエンコーディングを確認します

権限エラー

エラーパターン	考えられる原因	修正方法
frappe.PermissionError	ユーザーにロール権限がありません	Role Permission Manager を確認します
API 呼び出しで 403	frappe.has_permission() がない、または @frappe.whitelist(allow_guest=True) の指定が正しくありません	権限チェックまたはゲストフラグを追加します
リストビューが空	ユーザー権限によるフィルタリングです	該当ユーザーの User Permission を確認します
送信できない	ロールに Submit 権限がありません	DocType に Submit 権限を追加します

デバッグツール

bench console（Python REPL）

bench --site {site} console
# Then:
frappe.get_doc("Sales Invoice", "SINV-00001")  # Inspect document
frappe.db.sql("SELECT name FROM `tabSales Invoice` LIMIT 5")  # Raw SQL
frappe.get_hooks("doc_events")  # Inspect active hooks
frappe.get_all("Server Script", filters={"disabled": 0}, fields=["name", "script_type"])

bench mariadb（SQL シェル）

bench --site {site} mariadb
-- Then:
SHOW CREATE TABLE `tabSales Invoice`;
SELECT * FROM `tabError Log` ORDER BY creation DESC LIMIT 10;

bench doctor

bench doctor  # Check scheduler, workers, background jobs

frappe.logger()

logger = frappe.logger("my_debug", allow_site=True)
logger.info(f"Variable value: {my_var}")
# Logs to: sites/{site}/logs/my_debug.log

ブラウザーの DevTools

Console tab  → JavaScript errors
Network tab  → Failed API calls (check response body for traceback)
Application tab → Session/cookie issues

ログファイルの場所

ログ	パス	内容
Frappe の Web	sites/{site}/logs/frappe.log	Web リクエストのエラー
Worker	sites/{site}/logs/worker.log	バックグラウンドジョブのエラー
Scheduler	sites/{site}/logs/scheduler.log	スケジュールされたタスクの出力
カスタムロガー	sites/{site}/logs/{name}.log	frappe.logger("{name}") の出力
Bench	~/.bench/logs/bench.log	Bench コマンドの出力
Error Log DocType	Desk > Error Log	UI から確認できるエラーレコード
Supervisor	/var/log/supervisor/	プロセスマネージャーのログ
nginx	/var/log/nginx/	HTTP リクエスト／プロキシのエラー

よくあるエラーパターンの一覧

エラーメッセージ	考えられる原因	修正方法	関連するスキル
Import not allowed in Server Scripts	Server Script で import を使用しています	frappe.utils.* を使用するか、Controller に移します	frappe-errors-serverscripts
Cannot read properties of undefined	フォームの読み込み前に JS がフィールドにアクセスしています	frm.doc.field の null チェックを追加します	frappe-errors-clientscripts
DocType X not found	アプリのインストールまたはマイグレーションが不足しています	bench migrate または bench install-app を実行します	frappe-ops-bench
Scheduler is not running	Worker が停止しています	bench doctor を実行し、Worker を再起動します	frappe-ops-bench
BrokenPipeError	長時間の処理で gunicorn がタイムアウトしています	長時間のタスクには frappe.enqueue() を使用します	frappe-impl-scheduler
ModuleNotFoundError	Python パッケージがインストールされていません	bench pip install {pkg} を実行します	frappe-ops-bench
Duplicate name	命名規則で名前が衝突しています	autoname または naming_series を確認します	frappe-syntax-doctypes
Insufficient Permission	操作に必要なロールがありません	Role Permissions を確認します	frappe-core-permissions
Cannot edit submitted document	docstatus=1 のドキュメントを変更しています	amend_doc() を使用するか、先にキャンセルします	frappe-errors-controllers
Invalid column	スキーマが同期されていません	bench migrate を実行します	frappe-errors-database

エージェントの出力形式

デバッグ出力は必ず次の形式で作成してください。

## Debug Report

### Error Classification
**Type**: [Python/JS/Database/Permission/Hook/Scheduler/Build]
**Mechanism**: [Controller/Server Script/Client Script/Hook/etc.]

### Root Cause
[One-sentence diagnosis]

### Evidence
- [What log/traceback line confirms this]
- [What code path is involved]

### Fix
[Corrected code or configuration change]

### Verification Steps
1. [How to confirm the fix works]
2. [What to check in logs/UI]

### Referenced Skills
- `frappe-*`: [what was consulted]

デバッグの判断ツリー

ERROR RECEIVED
|
+-- Has traceback?
|   +-- YES: Read LAST line first (actual error)
|   |   +-- Contains ".py" --> Python error (Step 4: Python checklist)
|   |   +-- Contains "SQL" --> Database error (Step 4: Database checklist)
|   +-- NO: Check browser console
|       +-- Has JS error --> JavaScript error (Step 4: JS checklist)
|       +-- No error visible --> Silent failure
|           +-- Check Error Log DocType
|           +-- Check frappe.log
|           +-- Add frappe.logger() statements
|
+-- Error after bench command?
|   +-- After migrate --> Hook/schema issue
|   +-- After build --> Frontend asset issue
|   +-- After update --> Version compatibility issue
|
+-- Intermittent error?
    +-- Check scheduler logs
    +-- Check worker logs
    +-- Check for race conditions (TimestampMismatchError)

診断チェックリストの完全版については、references/checklists.md を参照してください。 デバッグ手順の例については、references/examples.md を参照してください。 VS Code DAP の設定、bench console のパターン、mariadb の診断、プロファイリングツールについては、references/advanced-debugging.md を参照してください。