Troubleshoot NextPDF Connect

At a glance

Most failures fit one of five patterns: a malformed JavaScript Object Notation Remote Procedure Call (JSON-RPC) handshake, a missing application programming interface (API) key, a tool that is not installed in this tier, an unanswered confirmation challenge, or a store that workers do not share. Each pattern has a distinct signature.

Install

composer require nextpdf/server

Conceptual overview

The Model Context Protocol (MCP) transport returns JSON-RPC 2.0 error objects with standard codes. The Representational State Transfer (REST) transport returns Request for Comments (RFC) 7807 problem-details documents. Each document carries a type URL that identifies the condition. For environment problems, start with the diagnostics tools (diagnostic.doctor, diagnostic.capabilities). These tools are always in the core catalog.

API surface

MCP JSON-RPC error codes

Code	Name	Cause
`-32700`	Parse error	The line was not valid JSON
`-32600`	Invalid request	Not a JSON-RPC 2.0 message (missing `jsonrpc`/`method`)
`-32601`	Method not found	A method other than `initialize`, `tools/list`, `tools/call`
`-32602`	Invalid params	Missing `params.name` on `tools/call`
`-32603`	Internal error	The tool threw during execution

A tool that fails gracefully does not use these codes. Instead, it returns a successful JSON-RPC response with isError: true in the result and a text explanation, such as unknown tool, disabled by policy, or invalid arguments.

REST problem-details types

HTTP	`type` slug	Cause
`401`	`unauthorized`	Missing/invalid/disabled/expired API key
`403`	`capability-denied`	Key tier not entitled to the operation
`413`	`payload-too-large` / `tier-payload-exceeded`	Body exceeds the global or tier ceiling
`422`	`validation-failed`	Request body failed schema validation
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	A rate limit was hit
`404`	`not-found`	Unknown route or job/session id
`504`	(request timeout)	The operation exceeded the tier timeout

Code sample — Quick start

Run the environment health check. It does not need a document or confirmation:

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

Code sample — Production

Before you debug a “missing tool”, confirm which tools this deployment exposes:

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

or, against a running REST server:

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

Edge cases and gotchas

“Unknown tool” for a Pro/Enterprise tool. The tool’s package is not installed. The registry checks for provider classes and skips absent tiers without warning. This is expected, not a bug. Install nextpdf/premium alongside the server, or use a core tool. The error message includes the install path.
A tool I configured in enabled_tools does not appear. The allowlist intersects with discovered tools. It cannot add a tool that the registry did not find. Check the tier installation and any environment gates. For example, parse_pdf is opt-in through NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED.
tools/call returned text asking for a token. That is the confirmation challenge, not an error. Call the tool again within 300 seconds with _confirmation_token set to the issued token. See /connect/hitl-risk-tiers/.
The notification line produced no output. That is correct. A JSON-RPC message with no id is a notification, and the handler returns nothing. Send requests with an id to get responses.
A repeated request id returned a stale response. The handler removes duplicates by request id in a 64-entry buffer. Use a fresh id for each logical request.
Rate limits behave oddly across workers. The in-memory store is per-worker. To share counting, set NEXTPDF_REDIS_HOST and install ext-redis. See /connect/deployment/.
Documents vanish between requests. The in-memory document store is per-worker and bound by a time to live (document_ttl, default 1800 s). For cross-worker document continuity, use the Redis-backed store, use the session endpoints, or keep the full operation set in one synchronous render.
The server fell back to in-memory despite Redis config. The REST server falls back automatically if the Redis connection fails at boot. Check Redis reachability, and confirm ext-redis is present in the running image. Do not assume Redis is in use without verifying.
The server refuses to boot with a config error. A risk_level_overrides entry tried to downgrade an ApprovalRequired tool. The loader rejects this by design. Remove the downgrade; overrides may only raise risk.

Performance

If renders are slow under load, confirm that the worker pool is not saturated. Check the RoadRunner metrics endpoint. Then move long renders to the async job path so they do not hold workers. See /connect/production-usage/.

Security notes

Do not work around a 401 by exposing the unauthenticated MCP transport over a network; that removes authentication entirely. Fix the API key instead. Do not raise log verbosity to inspect tool arguments in a shared environment; argument payloads may be sensitive. See /connect/security-and-operations/.

Conformance

This page provides operational guidance. Protocol and security citations are pinned on /transports/mcp/, /transports/rest/, and /connect/security-and-operations/.