Troubleshooting
Troubleshooting starts from the failed proof path. Identify whether the failure comes from discovery, generated files, provider resources, Runtime Helpers, the CLI Dev Loop, Agent behavior, or host output before changing code.
Quick checks
| Symptom | First check | Proof path |
|---|---|---|
| Definition is missing | File path and default export shape | File conventions and .vitehub/** |
| Stable import fails | Vite Integration and generated TypeScript includes | Generated files |
| Provider build fails | Provider Selection and required resource ids | Provider output |
| Agent CLI cannot inspect or invoke | Running Vite server and hubAgent() registration | CLI |
| Agent changed behaviour | Agent Eval result and Agent Usage Record | Agent Evals |
| Agent proof times out | Dev-loop --timeout, agent.eval.testTimeout, or stalled provider/session setup | CLI and Agent Evals |
| Runtime error lacks context | Package error family and diagnostics output | Errors and 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.
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 inspect generated host output.
pnpm vitehub provision run --provider cloudflare --dry-run
pnpm build
find dist -maxdepth 4 -type f | sort
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.
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 to choose the right check.
- Use Errors and diagnostics to classify the failure.
- Use Local development to restart from the full proof map.