> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Build failures

> When the type-checker rejects the build. Diagnosis and fixes.

Builds fail when:

* TypeScript type-checking fails.
* A required env var is missing.
* A Convex schema migration conflicts.

vly auto-retries failed builds up to 3 times (the agent self-corrects). If it still fails after 3 retries, you'll see the build error in the deploy log.

## Common causes

<AccordionGroup>
  <Accordion title="Missing required env var" icon="key-round">
    Look for "process.env.X is undefined" in the build log. Set the env var in the appropriate environment.
  </Accordion>

  <Accordion title="Type mismatch from schema change" icon="x-circle">
    A schema field changed type but a query still references the old type. Re-prompt to fix, or hand-edit the query.
  </Accordion>

  <Accordion title="Import resolves to nothing" icon="search-x">
    Often after renaming a file. Cmd+Shift+F to find broken imports; fix the path.
  </Accordion>

  <Accordion title="Convex migration conflict" icon="alert-triangle">
    Two branches changed the same field. Resolve by picking one; re-prompt the conflicting branch with the resolution.
  </Accordion>
</AccordionGroup>

## Reading the build log

In vly's editor → Deploys → click the failed build. The log shows:

1. Build start time.
2. Type-check pass (or fail with specific errors).
3. Bundle pass.
4. Deploy pass.

The error usually has a file:line indicator pointing at the problem.

## Fixing

The fastest fix path:

<Steps>
  <Step title="Read the error message">
    Most errors are clear once read carefully.
  </Step>

  <Step title="Re-prompt to fix">
    "Fix the TypeScript error on line 42 of `components/TaskRow.tsx`." The agent reads the error and applies the right fix.
  </Step>

  <Step title="Or hand-edit in Code mode">
    For one-line fixes, manual is fastest.
  </Step>

  <Step title="If the schema is the issue">
    Check `convex/schema.ts` and the affected query for type alignment.
  </Step>
</Steps>

## Related

<CardGroup cols={3}>
  <Card title="Common errors" icon="alert-triangle" href="/troubleshooting/common-errors">
    Specific patterns.
  </Card>

  <Card title="Convex migrations" icon="arrow-right-left" href="/convex/migrations">
    Schema evolution.
  </Card>

  <Card title="Debugging workflow" icon="bug" href="/troubleshooting/debugging-workflow">
    Systematic approach.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.