Troubleshooting

Troubleshooting / FAQ

Quick fixes for common FastRMCP issues. See Observability for logging tips.

Transport Issues

• SSE: 400 Bad Request on POST — Include "connectionId" from the first SSE event in every POST; if multiple clients connect without IDs, the server rejects ambiguous requests.
• WebSocket server-initiated messages go nowhere — Set metadata.connectionId in the request params to target a specific connection; otherwise only the current connection receives it.
• Port conflicts — Change example ports (3000/3001) or kill processes (lsof -ti:3000 | xargs kill).

Schema & Params

• "Invalid params" — Ensure tool/resource structs derive Serialize + Deserialize; check argument names match signature (case-sensitive).
• Optional fields — Use Option<T> for optional params; sending null maps to None.
• URI template mismatch — Resource URIs must match patterns exactly (e.g., file:///tmp/a.txt vs file:///{path}); overlapping templates cause ServerError -32002.

Metadata/Context

• Missing client info — Provide clientInfo during initialize; Context.client_info will be None otherwise.
• Progress/logs not visible — Use transports that support notifications (SSE/WS) and ensure the client listens for notifications/progress / notifications/message. STDIO still logs via tracing fallback.

Subscriptions

• No notifications — Verify you call notify_uri with valid ResourceContent and subscribers exist (subscription_count_for_uri > 0). Check transport connectionId handling (SSE) or connection targeting (WS).
• Stale subscriptions after restart — Recreate subscriptions from persisted state or ask clients to resubscribe; manager does not persist by default.

Middleware

• Unexpected rejections — Logging middleware first helps reveal which middleware returns errors. Remember order is the same as added for before_request and reversed for after_response.
• Auth always fails — Inspect request.params["metadata"] contents; browser clients may strip headers unless CORS allows them.

Debugging Steps

• Enable verbose logs: RUST_LOG=fastrmcp=debug,tower_http=debug cargo run --features full.
• Replay with examples/complete to isolate framework vs. app-level issues.
• Validate JSON-RPC shape with jq or jsonlint before sending.
• Check registry contents at startup: server.tool_registry().list()? etc. to confirm macros registered.

Related: Transports Guide • Subscriptions • Middleware Cookbook.

Back to Home