08 Troubleshooting

Server Function Works But HTTP Client Cannot Call It

Server functions are app-internal RPC-style calls. Use a server route under src/routes when external clients need a normal HTTP endpoint.

Route Returns message is required

Send JSON with the expected field:

curl -X POST http://localhost:3000/api/support \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}'

Provider Key Is Missing

Create the provider client only where server environment variables are available:

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) throw new Error("OPENAI_API_KEY is required");

Server Code Reaches The Client Bundle

Keep provider clients, agents, database clients, and scoped tool factories out of client components. Put client-safe schemas and types in separate files.

Streaming Does Not Flush

Use a server route, return a Response, and set NDJSON headers:

return new Response(agent.prompt(message).readableStream(), {
  headers: { "Content-Type": "application/x-ndjson" },
});

Also check host buffering and route timeouts.

Tool Authorization Is Wrong

Resolve the current user in the route or server function. Close over that user in request-scoped tools instead of trusting model-provided identifiers.

Next

Revisit Route Handler, Tools and Context, and Tool Errors.