Troubleshooting FAQ

This page is for operational fixes.

If you want product or architecture answers, use the main Vox FAQ.

Common Issues & Fixes

---

vox-mcp connection timeout

Cause: The vox-mcp binary is missing or not in the expected path. The AI Agent reads the binary path from vox-agent.json.

Fix:

# Build the binary
cargo build -p vox-mcp

# Check it exists
ls target/debug/vox-mcp*

# Re-run doctor
vox doctor

If you’re using a release build, make sure vox-agent.json points to target/release/vox-mcp.

---

vox-lsp not starting or LSP crashes

Cause: The LSP binary is not built, or it panics on startup with an invalid project.

Fix:

# Build the LSP binary
cargo build -p vox-lsp

# Run it manually to see errors
target/debug/vox-lsp --stdio 2>&1 | head -20

Check target/debug/vox-lsp.stderr.log if it exists.

---

Port conflict on vox gui

Cause: Port 8080 (default) is already in use.

Fix:

# Check what's using the port
netstat -ano | findstr :8080

# Kill the process by PID (Windows)
taskkill /PID <PID> /F

# Or launch on a different port
VOX_GUI_PORT=8090 vox gui

---

Shell completions not working

Fix: Generate and source completions for your shell:

# Bash
vox completions bash > ~/.local/share/bash-completion/completions/vox

# Zsh
vox completions zsh > ~/.zfunc/_vox

# PowerShell
vox completions powershell >> $PROFILE

---

vox_map_agent_session failing

Cause: The session ID is already mapped, or the agent doesn’t exist.

Fix: Check current session-to-agent mappings in the orchestrator runtime, or restart the MCP server: vox mcp.

---

Workspace compilation errors after update

Cause: A Vox AST or HIR struct gained a new required field (e.g., filter_fields).

Fix: Run cargo check --workspace and read the specific E0063 missing field errors. These are structural changes to the Vox type system and require adding the new field at the construction site.

---

Agent scoped to the wrong files

Cause: The scope: line in .vox/agents/<agent>.md doesn’t match the edited file’s path.

Fix: Update .vox/agents/<agent>.md to update the scope: field for the agent.

---

GUI shows no agents

Cause: The orchestrator has no active agents. Agents are only spawned when tasks are submitted.

Fix: Submit a task via an AI session to spawn an agent, then reload the GUI.

Compiler Diagnostics & Error Codes

The Vox compiler provides structured diagnostic codes to help you (and AI agents) fix code rapidly.

E0001: Argument count mismatch

Message: Argument count mismatch: expected X arguments, found Y Cause: You called a function with the wrong number of parameters. Fix: Match the function signature. If you want optional arguments, use Option[T].

E0002: Tuple size mismatch

Message: Tuple size mismatch: expected X, found Y Cause: Attempting to destructure or assign a tuple of different lengths.

E0003: Function arity mismatch

Message: Function arity mismatch: expected X, found Y Cause: Occurs during higher-order function passing where the callback signature doesn’t match the expected parameter count.

E0063: Missing record fields

Message: Missing record fields: [field_name] Cause: You instantiated a struct or table without providing all required non-Option fields. Fix: Provide the missing fields or update the type definition to use Option[T].

E0101: Immutable assignment

Message: Cannot assign to immutable variable X Cause: Attempting to mutate a variable not declared with mut. Fix: Change let x = ... to let mut x = ....

E0404: Module search failure

Message: Failed to resolve module X Cause: The imported file or crate is missing from the search path. Fix: Check your import paths and ensure the dependency is in your project or listed in vox.lock.

---

Further Operations

• Vox FAQ — Architectural and conceptual Q&A.
• vox doctor — Automates environment verification.
• Contributor Hub — If you’ve found a compiler bug.