Troubleshooting: Vercel AI SDK path
Cross-cutting issues that are not specific to one challenge. Each challenge README has a “Traps” section for its own failure modes; this covers the wider stuff.
npm run fN/npm run pN fails with a module or path error
Section titled “npm run fN/npm run pN fails with a module or path error”Run every challenge command from the vercel-ai-sdk/ root, not from inside a
challenge folder.
ai, ai-sdk-ollama, or zod not found
Section titled “ai, ai-sdk-ollama, or zod not found”You have not installed the dependencies. From vercel-ai-sdk/:
tsx: command not found
Section titled “tsx: command not found”Dependencies did not install, or you are calling tsx globally. Use the project’s:
Or reinstall: rm -rf node_modules && npm install.
Node version too old
Section titled “Node version too old”Needs Node 22+.
Choosing a model
Section titled “Choosing a model”Switch between Ollama and Google
Section titled “Switch between Ollama and Google”Edit one line in shared/model.ts:
For Google, set the key first: export GOOGLE_GENERATIVE_AI_API_KEY=.... Challenge
files never change; they import model from this one file.
Ollama: fetch failed / ECONNREFUSED 127.0.0.1:11434
Section titled “Ollama: fetch failed / ECONNREFUSED 127.0.0.1:11434”Ollama is not running. Start it, then verify:
Ollama: model not pulled
Section titled “Ollama: model not pulled”Ollama is on another host
Section titled “Ollama is on another host”verify.ts honours the same variable.
Observability (the console trace)
Section titled “Observability (the console trace)”No trace prints
Section titled “No trace prints”Traces print to your console, above your own logs, for every challenge from f2 on.
Run a challenge with its npm run script (f2 onward load the tracing bootstrap via
--import ./instrument.ts). f1 is deliberately untraced, so it shows no spans. A
bare tsx ... without --import is also untraced; use the npm run scripts.
A run finishes but the spans look truncated
Section titled “A run finishes but the spans look truncated”The pretty exporter abbreviates long attribute values (the prompt, the response) so the tree stays readable. That is expected. The load-bearing attributes (model, finish reason, token usage) print in full.
I want to send traces to a real backend instead
Section titled “I want to send traces to a real backend instead”instrument.ts uses init({ debug: "pretty" }) for console output. Add an
endpoint (and drop or keep debug) to send the same spans to any OTLP backend,
for example Honeycomb or Grafana. The workshop stays console-only so nothing extra
has to run.
Tool calls
Section titled “Tool calls”The model never calls my tool
Section titled “The model never calls my tool”Two usual causes. The tool is not in the agent’s tools: { ... } map, so the model
cannot see it. Or its description is too vague for the model to know when to use it
(this is the whole lesson of f5). Make the description say plainly what the tool is
for and when to call it.
The tool fires but the model ignores the result
Section titled “The tool fires but the model ignores the result”Push the instructions: “report exactly what the tool returns; never invent.” Small models sometimes call a tool then answer from memory anyway.
A tool throws and I expected a crash
Section titled “A tool throws and I expected a crash”The AI SDK catches a thrown tool error and reports it back to the model, so the agent
keeps running. To control the message and add recovery guidance, return
{ error: "..." } instead of throwing. That is the lesson of p5.
MCP (mcp)
Section titled “MCP (mcp)”“Could not reach the MCP server”
Section titled ““Could not reach the MCP server””The server is not running. mcp needs two terminals:
Port 4320 is in use
Section titled “Port 4320 is in use”Change PORT in mcp/mcp-server.ts and the matching url in
mcp/start/agent.ts (and finish/agent.ts).
No [tool fired] findHotel line
Section titled “No [tool fired] findHotel line”Expected: that log lives in local tools, and findHotel runs on the server. Confirm
the call in the “tools called this run” line the agent prints, or in the console trace.
RAG track (r1–r2)
Section titled “RAG track (r1–r2)”Only needed if you chose the RAG track after Foundations. Foundations, Patterns, and Full-Stack do not use embeddings.
embeddinggemma not found
Section titled “embeddinggemma not found”npm run verify checks this when Ollama is up. The check is labelled
“RAG track only”; you can ignore it if you are not doing r1–r2.
First npm run r1 or npm run r2 pauses for several seconds
Section titled “First npm run r1 or npm run r2 pauses for several seconds”Ollama is loading the embedding model and batch-embedding the documents. It is not hung. Later queries are faster.
Chat runs on Gemini but RAG fails
Section titled “Chat runs on Gemini but RAG fails”Retrieval always uses a local Ollama embedder (embeddinggemma), separate from the
chat model in shared/model.ts. ollama serve must be running and the model pulled,
even when chat uses Gemini.
r1: scores are all 0.000 and the Swiss Alps appears for “warm beach”
Section titled “r1: scores are all 0.000 and the Swiss Alps appears for “warm beach””Expected in the starter: search ignores the query until you complete the TODOs (embed
the query, score by cosine similarity, sort and take top K). Compare with
npm run solution:r1.
r2: food passages score around 0.25 and snippets show opening paragraphs
Section titled “r2: food passages score around 0.25 and snippets show opening paragraphs”Expected in the starter: chunk() returns the whole guide as one vector. Split on blank
lines (see README TODO 1). Compare with npm run solution:r2.
Full-stack track (a cloned template)
Section titled “Full-stack track (a cloned template)”The full-stack track is a separate template, not part of this repo’s scripts. Clone it with
npx @jagreehal/ai-workshop fullstack-hono, then follow that folder’s own README.md for
setup (npm install, npm run dev) and troubleshooting.
TypeScript
Section titled “TypeScript”await is only valid in async functions
Section titled “await is only valid in async functions”The function is not async. Use async function main() { ... }.
A Promise prints instead of a value
Section titled “A Promise prints instead of a value”A missing await. Find the call (often agent.generate(...)) that is not awaited.
Type errors after editing a tool
Section titled “Type errors after editing a tool”The Zod inputSchema and the execute argument must agree. If
inputSchema: z.object({ city: z.string() }), then execute: async ({ city }) => ....
Verify
Section titled “Verify”Verify passes but a challenge fails
Section titled “Verify passes but a challenge fails”Verify checks the underlying primitives. If it passes but a challenge fails, the issue
is in your challenge edits, not your setup. Compare with that challenge’s
finish/agent.ts.
Verify is slow
Section titled “Verify is slow”A model call is taking a while; verify prints (slow: …ms). On Ollama this is normal
on first run while the model loads. Re-run; later runs are faster.