# Troubleshooting

Use this page when a local check, build, or deploy fails. First find the layer
that failed: discovery, generated files, provider resources, Runtime Helpers, the
Agent Dev Loop, Agent behavior, or host output. Then change code in that layer.

## Quick checks

| Symptom | First check | Proof path |
| --- | --- | --- |
| Definition is missing | File path and default export shape | [File conventions](https://vitehub.dev/docs/reference/file-conventions) and `.vitehub/**` |
| Stable import fails | Vite Integration and generated TypeScript includes | [Generated files](https://vitehub.dev/docs/development/generated-files) |
| Provider build fails | Provider Selection and required resource ids | [Provider output](https://vitehub.dev/docs/reference/provider-output) |
| Agent CLI cannot inspect or invoke | Running Vite server and `agent` enabled in `vitehub()` | [CLI](https://vitehub.dev/docs/development/cli) |
| Agent changed behaviour | Agent Eval result and Agent Usage Record | [Agent Evals](https://vitehub.dev/docs/agents/evals) |
| Agent proof times out | Dev-loop `--timeout`, `agent.eval.testTimeout`, or stalled provider/session setup | [CLI](https://vitehub.dev/docs/development/cli) and [Agent Evals](https://vitehub.dev/docs/agents/evals) |
| Runtime error lacks context | Package error family and diagnostics output | [Errors and diagnostics](https://vitehub.dev/docs/reference/errors-diagnostics) |

## Discovery failures

Discovery Identity comes from the file location.
Do not add inline ids to force a name; move the file to the expected convention instead.

```txt [File tree]
server/
  agents/
    support.ts
  queues/
    welcome-email.ts
  workspaces/
    docs.ts
```

If a package requires a direct default export of a Definition Boundary Helper, avoid named aggregate exports and local indirection.
The direct export keeps Build-Extracted Definition Options inspectable.

## Provider failures

Provider failures usually belong to one of three layers: missing provider credentials, missing Provision State, or invalid Provider Output.
Dry-run provisioning first, then build and inspect the generated host output.

```bash [Terminal]
pnpm vitehub provision run --provider cloudflare --dry-run
pnpm build
pnpm vitehub inspect provider-output
```

A build also fails when the preset cannot provide an enabled feature. For
example, `queue: true` fails on the `node`, `netlify`, and `deno` presets, and
`rateLimit: true` fails on `vercel`, `netlify`, and `deno`. Disable the feature
or configure an explicit provider through the owner package. The
[support matrix](https://vitehub.dev/docs/frameworks-hosts/support-matrix) lists the providers for
each host.

## Agent failures

Separate Agent runtime failures from model behavior.
Use `vitehub agent dev` to inspect one interactive Agent Invocation, then use Agent Evals when the failure is repeatable behavior.
If the proof is timing out before it reaches the interesting failure, increase the dev-loop inactivity `--timeout` or the Agent Eval Runner `agent.eval.testTimeout` in `vite.config.ts`.

```bash [Terminal]
pnpm vitehub agent eval server/agents/support.eval.ts --output .vitehub/evals/support.json
```

When the Agent Dev Loop reports `Agent Invocation Stream timed out after <ms> of inactivity`, first decide whether the streamed invocation is expected to stay silent longer than the default timeout. If so, rerun with `vitehub agent dev --timeout <ms>`. If the timeout is surprising, inspect the Agent Driver boundary and any Workspace or provider session setup before changing prompts. For Capability CLI and `!` Workspace commands, the same option is a wall-clock command deadline because those operations do not emit Agent Invocation Stream events.

## When to escalate

Escalate to the owning ViteHub package when the same failure reproduces outside application code. Include the smallest reproduction, the generated artifact that failed, and the narrow command that demonstrates the problem.

## Next steps

- Use [Verification](https://vitehub.dev/docs/development/verification) to choose the right check.
- Use [Errors and diagnostics](https://vitehub.dev/docs/reference/errors-diagnostics) to classify the failure.
- Use [Local development](https://vitehub.dev/docs/development) to restart from the full proof map.