NextPDF Connect のトラブルシューティング

概要

ほとんどの障害は、次の 5 つのグループのいずれかに分類できます。不正な形式の JSON-RPC ハンドシェイク、欠落した API キー、このティアにインストールされていないツール、未応答の確認チャレンジ、ワーカー間で共有されていないストアです。各グループには固有のシグネチャがあります。

インストール

composer require nextpdf/server

概念の概要

MCP トランスポートは、標準コードを持つ JSON-RPC 2.0 エラーオブジェクトを返します。REST トランスポートは、RFC 7807 の problem-details ドキュメントを返します。それぞれに、条件を識別する type URL が含まれます。環境の問題を調べる場合は、まず診断ツール（diagnostic.doctor、diagnostic.capabilities）を使用してください。これらのツールは常にコアカタログに含まれています。

API サーフェス

MCP JSON-RPC エラーコード

コード	名前	原因
`-32700`	パースエラー	有効な JSON ではない行
`-32600`	無効なリクエスト	JSON-RPC 2.0 メッセージではない形式（`jsonrpc`/`method` が欠落）
`-32601`	メソッドが見つかりません	許可されたメソッド以外：`initialize`、`tools/list`、`tools/call`
`-32602`	無効なパラメーター	対象メソッド `tools/call` でのパラメーター `params.name` の欠落
`-32603`	内部エラー	実行中のツールによる例外のスロー

ツールが 正常に 失敗した場合、これらのコードは使用されません。代わりに、成功した JSON-RPC レスポンスが返され、その結果には isError: true と、不明なツール、ポリシーによる無効化、無効な引数といったテキスト説明が含まれます。

REST problem-details タイプ

HTTP	`type` スラッグ	原因
`401`	`unauthorized`	API キーの欠落/不正/無効化/期限切れ
`403`	`capability-denied`	キーのティアにおけるこの操作の権限不足
`413`	`payload-too-large` / `tier-payload-exceeded`	ボディのグローバルまたはティア上限超過
`422`	`validation-failed`	リクエストボディのスキーマ検証失敗
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	レート制限への到達
`404`	`not-found`	不明なルートまたは job/session ID
`504`	（リクエストタイムアウト）	操作のティアタイムアウト超過

コードサンプル — クイックスタート

環境のヘルスチェックを実行します。ドキュメントも確認も不要です。

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"diag","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"diagnostic.doctor","arguments":{}}}
EOF

コードサンプル — 本番

「見つからないツール」をデバッグする前に、このデプロイメントで公開されているツールを確認してください。

./vendor/bin/generate-skills --dry-run --list-tools

または、稼働中の REST サーバーに対して実行します。

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

エッジケースと注意点

Pro/Enterprise ツールで「Unknown tool」と表示される。 そのツールのパッケージがインストールされていません。レジストリはプロバイダークラスをプローブし、存在しないティアは警告なしでスキップします。これは想定どおりの動作であり、バグではありません。サーバーとあわせて nextpdf/premium をインストールするか、コアツールを使用してください。エラーメッセージにはインストールパスが含まれています。
enabled_tools で設定したツールが表示されない。 許可リストは、検出されたツールとの積集合として扱われます。レジストリが検出できなかったツールを追加することはできません。ティアのインストール状況と環境ゲートを確認してください。たとえば、parse_pdf は NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED によってオプトインで有効になります。
tools/call がトークンを求めるテキストを返した。 これは確認チャレンジであり、エラーではありません。発行されたトークンを設定した _confirmation_token を添えて、300 秒以内にツールを再度呼び出してください。/connect/hitl-risk-tiers/. を参照してください。
通知行が何も出力しなかった。 これは正しい動作です。id を持たない JSON-RPC メッセージは通知であり、ハンドラーは何も返しません。レスポンスを得るには、id を持つリクエストを送信してください。
繰り返し使ったリクエスト ID が古いレスポンスを返した。 ハンドラーは 64 エントリのバッファを使い、リクエスト ID によって重複を排除します。論理的なリクエストごとに新しい ID を使用してください。
ワーカー間でレート制限の動作がおかしい。 インメモリストアはワーカーごとです。カウントを共有するには、NEXTPDF_REDIS_HOST を設定し、ext-redis をインストールしてください。/connect/deployment/. を参照してください。
リクエスト間でドキュメントが消える。 インメモリのドキュメントストアはワーカー単位で、有効期間（document_ttl、デフォルト 1800 秒）の制限を受けます。ワーカー間でドキュメントを維持するには、Redis ベースのストア、セッションエンドポイント、または完全な操作セットを 1 回の同期レンダリング内に収める方法を使用してください。
Redis の設定があるにもかかわらず、サーバーがインメモリにフォールバックした。 REST サーバーは、起動時の Redis 接続に失敗すると自動的にフォールバックします。Redis への到達性を確認し、稼働中のイメージに ext-redis が存在することを確認してください。検証せずに Redis が使用されていると想定しないでください。
サーバーが設定エラーで起動を拒否する。 risk_level_overrides のエントリが ApprovalRequired ツールをダウングレードしようとしました。ローダーは設計上これを拒否します。ダウングレードを削除してください。オーバーライドはリスクを引き上げることのみが可能です。

パフォーマンス

負荷時にレンダリングが遅い場合は、ワーカープールが飽和していないか確認してください。RoadRunner のメトリクスエンドポイントも確認します。その後、長時間かかるレンダリングを非同期ジョブパスに移し、ワーカーが占有されないようにしてください。/connect/production-usage/. を参照してください。

セキュリティに関する注意

未認証の MCP トランスポートをネットワーク上に公開して 401 を回避しないでください。これは認証を完全に取り除いてしまいます。代わりに API キーを修正してください。共有環境でツール引数を確認する目的で、ログの詳細度を上げないでください。引数ペイロードには機微な情報が含まれる可能性があります。/connect/security-and-operations/. を参照してください。

準拠

このページは運用ガイダンスです。プロトコルとセキュリティの引用は、/transports/mcp/、/transports/rest/、/connect/security-and-operations/. に固定されています。