NextPDF Connect: Fehlerbehebung

Auf einen Blick

Die meisten Fehler fallen in eine von fünf Gruppen: ein fehlerhafter JSON-RPC-Handshake, ein fehlender API-Key, ein Tool, das in dieser Stufe nicht installiert ist, eine unbeantwortete Bestätigungs-Challenge oder ein Store, der nicht über die Worker hinweg geteilt wird. Jede Gruppe hat eine eindeutige Signatur.

Installation

composer require nextpdf/server

Konzeptioneller Überblick

Der MCP-Transport gibt JSON-RPC-2.0-Fehlerobjekte mit Standardcodes zurück. Der REST-Transport gibt Problem-Details-Dokumente nach RFC 7807 zurück. Beide enthalten eine type-URL, die die jeweilige Bedingung identifiziert. Beginnen Sie bei Umgebungsproblemen mit den Diagnose-Tools (diagnostic.doctor, diagnostic.capabilities). Diese Tools sind immer im Core-Katalog enthalten.

API-Oberfläche

MCP-JSON-RPC-Fehlercodes

Code	Name	Ursache
`-32700`	Parse-Fehler	Die Zeile war kein gültiges JSON
`-32600`	Ungültige Anfrage	Keine JSON-RPC-2.0-Nachricht (`jsonrpc`/`method` fehlt)
`-32601`	Methode nicht gefunden	Eine andere Methode als `initialize`, `tools/list`, `tools/call`
`-32602`	Ungültige Parameter	Fehlendes `params.name` bei `tools/call`
`-32603`	Interner Fehler	Das Tool hat während der Ausführung eine Exception geworfen

Ein Tool, das kontrolliert fehlschlägt, verwendet diese Codes nicht. Stattdessen gibt es eine erfolgreiche JSON-RPC-Antwort zurück, deren Result isError: true sowie eine Texterklärung enthält, etwa für ein unbekanntes Tool, eine per Policy deaktivierte Funktion oder ungültige Argumente.

REST-Problem-Details-Typen

HTTP	`type`-Slug	Ursache
`401`	`unauthorized`	Fehlender/ungültiger/deaktivierter/abgelaufener API-Key
`403`	`capability-denied`	Die Stufe des Keys ist nicht für die Operation berechtigt
`413`	`payload-too-large` / `tier-payload-exceeded`	Der Body überschreitet die globale oder die Stufen-Obergrenze
`422`	`validation-failed`	Der Request-Body hat die Schema-Validierung nicht bestanden
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	Ein Rate-Limit wurde erreicht
`404`	`not-found`	Unbekannte Route oder job/session-ID
`504`	(Request-Timeout)	Die Operation hat das Timeout der Stufe überschritten

Codebeispiel — Schnellstart

Führen Sie den Health-Check der Umgebung aus. Er benötigt weder ein Dokument noch eine Bestätigung:

./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

Codebeispiel — Produktion

Prüfen Sie, welche Tools dieses Deployment bereitstellt, bevor Sie ein „fehlendes Tool“ debuggen:

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

oder, gegen einen laufenden REST-Server:

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

Sonderfälle und Stolperfallen

„Unbekanntes Tool“ bei einem Pro-/Enterprise-Tool. Das Paket des Tools ist nicht installiert. Die Registry prüft, ob Provider-Klassen vorhanden sind, und überspringt fehlende Stufen ohne Warnung. Das ist erwartetes Verhalten, kein Bug. Installieren Sie nextpdf/premium zusätzlich zum Server oder verwenden Sie ein Core-Tool. Die Fehlermeldung enthält den Installationspfad.
Ein in enabled_tools konfiguriertes Tool erscheint nicht. Die Allowlist wird mit den erkannten Tools geschnitten. Sie kann kein Tool hinzufügen, das die Registry nicht gefunden hat. Prüfen Sie die Installation der Stufe und etwaige Umgebungs-Gates. Beispielsweise ist parse_pdf per Opt-in über NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED aktivierbar.
tools/call hat Text zurückgegeben, in dem nach einem Token gefragt wird. Das ist die Bestätigungs-Challenge, kein Fehler. Rufen Sie das Tool innerhalb von 300 Sekunden erneut auf und setzen Sie _confirmation_token auf das ausgestellte Token. Siehe /connect/hitl-risk-tiers/.
Die Notification-Zeile hat keine Ausgabe erzeugt. Das ist korrekt. Eine JSON-RPC-Nachricht ohne id ist eine Notification, und der Handler gibt nichts zurück. Senden Sie Requests mit einer id, um Antworten zu erhalten.
Eine erneut verwendete Request-ID hat eine veraltete Antwort zurückgegeben. Der Handler entfernt Duplikate anhand der Request-ID in einem Buffer mit 64 Einträgen. Verwenden Sie für jeden logischen Request eine frische ID.
Rate-Limits verhalten sich über Worker hinweg unerwartet. Der In-Memory-Store gilt pro Worker. Setzen Sie für eine gemeinsame Zählung NEXTPDF_REDIS_HOST und installieren Sie ext-redis. Siehe /connect/deployment/.
Dokumente verschwinden zwischen Requests. Der In-Memory-Dokument-Store gilt pro Worker und ist an eine Time to Live gebunden (document_ttl, Standard 1800 s). Verwenden Sie für Dokumentkontinuität über Worker hinweg den Redis-gestützten Store, die Session-Endpunkte oder halten Sie den gesamten Operationssatz in einem synchronen Render.
Der Server ist trotz Redis-Konfiguration auf In-Memory zurückgefallen. Der REST-Server fällt automatisch zurück, wenn die Redis-Verbindung beim Boot fehlschlägt. Prüfen Sie die Erreichbarkeit von Redis und stellen Sie sicher, dass ext-redis im laufenden Image vorhanden ist. Gehen Sie nicht ohne Prüfung davon aus, dass Redis verwendet wird.
Der Server bricht den Boot mit einem Konfigurationsfehler ab. Ein Eintrag in risk_level_overrides hat versucht, ein ApprovalRequired-Tool herabzustufen. Der Loader weist dies absichtlich zurück. Entfernen Sie die Herabstufung; Overrides dürfen das Risiko nur erhöhen.

Performance

Wenn Render-Vorgänge unter Last langsam sind, stellen Sie sicher, dass der Worker-Pool nicht ausgelastet ist. Prüfen Sie den RoadRunner-Metrics-Endpunkt. Verlagern Sie dann lange Render-Vorgänge auf den asynchronen Job-Pfad, damit Worker nicht blockiert werden. Siehe /connect/production-usage/.

Sicherheitshinweise

Geben Sie den nicht authentifizierten MCP-Transport nicht über ein Netzwerk frei, um einen 401 zu umgehen; dadurch wird die Authentifizierung vollständig entfernt. Beheben Sie stattdessen den API-Key. Erhöhen Sie die Log-Ausführlichkeit nicht, um Tool-Argumente in einer gemeinsam genutzten Umgebung zu inspizieren; Argument-Payloads können sensibel sein. Siehe /connect/security-and-operations/.

Konformität

Diese Seite ist eine betriebliche Anleitung. Die Zitate zu Protokoll und Sicherheit sind in /transports/mcp/, /transports/rest/ und /connect/security-and-operations/ verankert.

Siehe auch

/connect/tool-catalog/ — was der Core-Katalog enthält und warum die Anzahl variiert
/connect/hitl-risk-tiers/ — Bestätigungs-Challenges im Detail
/connect/deployment/ — Redis, Worker-Pools und Store-Sharing
/connect/security-and-operations/ — Authentifizierungsfehler und Posture