Problemen oplossen met NextPDF Connect

In een oogopslag

De meeste fouten vallen in een van vijf patronen: een ongeldig gevormde JavaScript Object Notation Remote Procedure Call (JSON-RPC)-handshake, een ontbrekende application programming interface (API)-sleutel, een tool die voor dit niveau niet is geïnstalleerd, een onbeantwoorde bevestigingsuitdaging of opslag die werkers niet delen. Elk patroon heeft een eigen herkenningspunt.

Installeren

composer require nextpdf/server

Conceptueel overzicht

De transportlaag voor Model Context Protocol (MCP) retourneert JSON-RPC 2.0-foutobjecten met standaardcodes. De transportlaag voor Representational State Transfer (REST) retourneert problem-details-documenten volgens Request for Comments (RFC) 7807. Elk document bevat een type-URL die aangeeft om welke conditie het gaat. Begin bij omgevingsproblemen met de diagnosetools (diagnostic.doctor, diagnostic.capabilities). Deze tools staan altijd in de core-catalogus.

API-oppervlak

MCP JSON-RPC-foutcodes

Code	Naam	Oorzaak
`-32700`	Parsefout	De regel was geen geldige JSON
`-32600`	Ongeldige aanvraag	Geen JSON-RPC 2.0-bericht (`jsonrpc`/`method` ontbreekt)
`-32601`	Methode niet gevonden	Een andere methode dan `initialize`, `tools/list`, `tools/call`
`-32602`	Ongeldige params	Ontbrekende `params.name` bij `tools/call`
`-32603`	Interne fout	De tool veroorzaakte tijdens de uitvoering een uitzondering

Een tool die gecontroleerd faalt, gebruikt deze codes niet. In plaats daarvan retourneert hij een geslaagd JSON-RPC-antwoord met isError: true in het resultaat en een tekstuele uitleg, bijvoorbeeld dat de tool onbekend is, door beleid is uitgeschakeld of ongeldige argumenten kreeg.

REST problem-details-typen

HTTP	`type`-slug	Oorzaak
`401`	`unauthorized`	Ontbrekende/ongeldige/uitgeschakelde/verlopen API-sleutel
`403`	`capability-denied`	Het sleutelniveau heeft geen recht op de bewerking
`413`	`payload-too-large` / `niveau-payload-exceeded`	De body overschrijdt de globale bovengrens of die van het niveau
`422`	`validation-failed`	De aanvraagbody heeft schemavalidatie niet gehaald
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	Een rate limit is bereikt
`404`	`not-found`	Onbekende route of job/session-id
`504`	(aanvraagtime-out)	De bewerking overschreed de time-out voor het niveau

Codevoorbeeld — Snelstart

Voer de gezondheidscontrole voor de omgeving uit. Daarvoor is geen document of bevestiging nodig:

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

Codevoorbeeld — Productie

Controleer, voordat je een „ontbrekende tool” onderzoekt, welke tools deze deployment beschikbaar stelt:

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

of tegen een draaiende REST-server:

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

Randgevallen en valkuilen

„Unknown tool” voor een Pro/Enterprise-tool. Het pakket voor de tool is niet geïnstalleerd. Het register controleert providerklassen en slaat ontbrekende niveaus zonder waarschuwing over. Dit is verwacht gedrag, geen bug. Installeer nextpdf/premium naast de server, of gebruik een core-tool. De foutmelding bevat het installatiepad.
Een tool die ik in enabled_tools heb geconfigureerd, verschijnt niet. De allowlist wordt beperkt tot de doorsnede met de ontdekte tools. Hij kan geen tool toevoegen die het register niet heeft gevonden. Controleer de installatie op dit niveau en eventuele omgevingspoorten. Zo is parse_pdf opt-in via NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED.
tools/call retourneerde tekst die om een token vraagt. Dat is de bevestigingsuitdaging, geen fout. Roep de tool binnen 300 seconden opnieuw aan met _confirmation_token ingesteld op het uitgegeven token. Zie /connect/hitl-risk-niveaus/.
De notification-regel leverde geen uitvoer op. Dat is verwacht. Een JSON-RPC-bericht zonder id is een notification, en de handler retourneert niets. Stuur aanvragen met een id om antwoorden te krijgen.
Een opnieuw gebruikte aanvraag-id leverde een verouderd antwoord op. De handler ontdubbelt op aanvraag-id in een buffer van 64 items. Gebruik voor elke logische aanvraag een nieuwe id.
Rate limits gedragen zich vreemd tussen werkers. De in-memory opslag is per werker. Stel NEXTPDF_REDIS_HOST in en installeer ext-redis om de tellingen te delen. Zie /connect/deployment/.
Documenten verdwijnen tussen aanvragen. De in-memory documentopslag geldt per werker en is gebonden aan een time to live (document_ttl, standaard 1800 s). Gebruik voor documentcontinuïteit tussen werkers de door Redis ondersteunde opslag, gebruik de session-endpoints of houd de volledige bewerkingsset in één synchrone weergave.
De server viel terug op in-memory ondanks de Redis-configuratie. De REST-server valt automatisch terug als de Redis-verbinding bij het opstarten mislukt. Controleer of Redis bereikbaar is en bevestig dat ext-redis aanwezig is in de draaiende image. Ga er niet zonder verificatie van uit dat Redis in gebruik is.
De server weigert op te starten met een configuratiefout. Een risk_level_overrides-vermelding probeerde een ApprovalRequired-tool te downgraden. De loader weigert dat bewust. Verwijder de downgrade; overrides mogen het risico alleen verhogen.

Prestaties

Controleer, als weergaven onder belasting traag zijn, of de werkerpool niet verzadigd is. Controleer het RoadRunner-metrics-endpoint. Verplaats vervolgens lange weergaven naar het asynchrone job-pad, zodat ze geen werkers bezet houden. Zie /connect/production-usage/.

Beveiligingsnotities

Omzeil een 401 niet door de niet-geauthenticeerde MCP-transportlaag over een netwerk beschikbaar te stellen; dat verwijdert de authenticatie volledig. Los in plaats daarvan het probleem met de API-sleutel op. Verhoog de log-verbosity niet om tool-argumenten te inspecteren in een gedeelde omgeving; argument-payloads kunnen gevoelig zijn. Zie /connect/security-and-operations/.

Conformiteit

Deze pagina biedt operationele richtlijnen. Protocol- en beveiligingscitaten zijn vastgelegd op /transports/mcp/, /transports/rest/ en /connect/security-and-operations/.

Zie ook

/connect/tool-catalog/ — wat de core-catalogus bevat en waarom het aantal varieert
/connect/hitl-risk-niveaus/ — bevestigingsuitdagingen in detail
/connect/deployment/ — Redis, werkerpools en het delen van opslag
/connect/security-and-operations/ — authenticatiefouten en beveiligingshouding