Build failures

When a build fails — yours or the Deploy button's — the verbatim compiler output lands in the response. This page covers the most common shapes and what to do about each.

TypeScript: Cannot find name 'X'

./src/lib/db.ts:34:54
Type error: Cannot find name 'ProductDoc'.

> 34 | export async function products(): Promise<Collection<ProductDoc>> {

Cause: ProductDoc is used in the file but not imported. The dev server tolerates this; the production build doesn't.

Fix: ask the agent to add the missing import. The actual fix is usually one line at the top of the file:

import type { ProductDoc } from "./types";

If multiple files have similar misses, the agent can do them in one turn:

Find every file that uses ProductDoc without importing it. Add the import. Then run the build.

TypeScript: Property does not exist on type

Type error: Property 'emails' does not exist on type 'User'.

Cause: the type definition and the call site drifted. The agent added a field to one but not the other.

Fix: ask the agent to align them.

The User type doesn't have an emails field but the code at src/lib/users.ts:42 references it. Either add the field to the type or fix the access. Pick the right one and explain why.

TypeScript: Type 'X' is not assignable to type 'Y'

Type error: Type '{ name: string; }' is not assignable to type 'User'.
  Property 'id' is missing in type '{ name: string; }' but required in type 'User'.

Cause: an object is being constructed without all required fields.

Fix: ask the agent to either add the missing field or make the field optional in the type.

The error in src/... says I'm constructing a User without an id. The right fix is to make id optional on creation (we'll generate it at insert time). Update the type and the call site.

Next.js: Module not found

Module not found: Error: Can't resolve '@/components/ProductCard' in '/workspace/projects/app/src/app'

Cause: a @/ import doesn't resolve. Either the file doesn't exist or tsconfig.json doesn't have the paths mapping set.

Fix: ask the agent to check both:

The build can't resolve @/components/ProductCard. Confirm the file exists at src/components/ProductCard.tsx. Confirm tsconfig.json has "paths": {"@/*": ["./src/*"]} and "baseUrl": ".". Fix whichever is wrong.

Next.js: Build worker exited with code: 1

The catch-all when nothing more specific surfaces. The actual cause is usually in the lines above the exited with code: 1 line — scroll up.

If the lines above are uninformative, ask the agent:

Run npm run build directly via command_run and show me the full output. Find the first error.

The full output usually has the root cause near the top.

Vite: Cannot find module

[vite:resolve] Failed to resolve import "lucide-react" from "src/components/Icon.tsx"

Cause: a package is imported but not installed.

Fix:

The build is missing lucide-react. Install it (npm install lucide-react) and re-run the build.

ESLint: Parsing error

Error: Parsing error: Unexpected token, expected ","

Cause: invalid syntax. The agent wrote code that doesn't parse.

Fix: ask for a re-read and re-write of that file.

File <path> has a syntax error at the location ESLint named. Re-read the file and rewrite that section so it parses.

Python: ModuleNotFoundError

ModuleNotFoundError: No module named 'fastapi'

Cause: the package isn't installed in the sandbox.

Fix:

agent: command_run "pip install fastapi"

Or if you're using a requirements file, ask the agent to add the package + reinstall:

Add fastapi to requirements.txt and re-run pip install -r requirements.txt.

Python: SyntaxError

The Python compiler caught syntax that doesn't parse. The error includes a ^ marker showing the column.

Python is rejecting <file> at line N. Re-read that section and fix the syntax.

Go: undefined: X

./main.go:42:5: undefined: BindParams

Cause: BindParams is referenced but not declared or imported.

Fix: ask the agent to either import it or declare it.

BindParams is undefined in main.go. Either import it from the right package or define it locally. Pick the right one based on the rest of the file.

Generic strategy when the error is opaque

Sometimes the preflight output is just a stack trace with no obvious "fix this file" hint.

What to do:

1. Ask the agent to read the relevant files.

   Read the files mentioned in the stack trace. Find the actual problem.

2. Ask the agent to try a minimal repro.

   Create a smaller version of the failing call and run it. See what changes.

3. Compare against a working version.

   This worked yesterday. Compare the current <file> to git HEAD and find what changed.

4. Search for the error message.

   Search GitHub / StackOverflow / the framework's issues for this exact error message. Tell me what people suggest.

   (A reasonably-resourced agent will use a web tool here.)

When in doubt, re-prompt

If the agent's fix attempt isn't converging, restate the failure in a fresh prompt — sometimes the model gets stuck on a wrong assumption and a clean reset breaks the loop:

Forget the previous attempts. Read the build output again, top to bottom. The actual error is <X>. Fix it.

Next

• Sandbox issues — when the sandbox itself isn't behaving.
• MCP wiring — when your harness can't talk to agentry.
• Deploy issues — when build is fine but deploy goes wrong.