Troubleshooting Guide

Solutions to common voria issues.

Installation Issues

"cargo not found"

Error:


terminal
command not found: cargo

Solution:


bash
# Install Rust
curl --proto '=https' --tlsvv0.0.3 -sSf https://sh.rustup.rs | sh

# Add to PATH
source $HOME/.cargo/env

# Verify
cargo --version

"Python command not found"

Error:


terminal
python3: command not found

Solution:


bash
# macOS
brew install python@3.11

# Ubuntu/Debian
sudo apt install python3

# Verify
python3 --version  # Should be 3.9+

"Build fails: can't find Tokio"

Error:


terminal
error[E0432]: unresolved import `tokio`

Solution:


bash
cd rust
cargo clean
cargo build

"Python import error"

Error:


terminal
ModuleNotFoundError: No module named 'voria'

Solution:


bash
cd python
pip install -e .

# Verify
python3 -c "import voria; print('OK')"

Runtime Issues

"Command hangs or takes forever"

Symptoms:

▶Command doesn't respond
▶Cursor stuck

Solutions:

▶

Check if Python process is stuck:


bash
# In another terminal
ps aux | grep python

# Kill the stuck process
pkill -f voria.engine

▶

Increase timeout:


bash
voria_TIMEOUT=3600 ./target/release/voria plan 1

▶

Use different LLM (might be down):


bash
./target/release/voria plan 1 --llm gemini

▶

Check network:


bash
# Can you access the LLM API?
curl -I https://api.openai.com/

"API Key not working"

Error:


terminal
Authentication failed
Unauthorized: Invalid API key

Solutions:

▶

Ensure key is set:


bash
echo $OPENAI_API_KEY  # Should not be empty

▶

Check key is correct:


bash
# Visit provider console to verify
# https://platform.openai.com/logout (wait, this logs out)
# https://platform.openai.com/account/api-keys

▶

Reconfigure:


bash
python3 -m voria.core.setup
# Choose provider → Enter key again → Select model

▶

Test key directly:


python
import httpx
import asyncio

async def test():
    client = httpx.AsyncClient()
    resp = await client.post(
        "https://api.openai.com/v1/models",
        headers={"Authorization": f"Bearer {KEY}"}
    )
    print(resp.status_code)
asyncio.run(test())

"Patch apply fails"

Error:


terminal
Failed to apply patch: hunk FAILED

Solutions:

▶

Check patch is valid:


bash
# Look at generated patchfile
voria issue 42 --dry-run --verbose

▶

Try fuzzy matching:


bash
voria issue 42 --patch-strategy fuzzy

▶

Rollback and retry:


bash
# Recovery from auto-backup
cp ~/.voria/backups/file_* restored_file

"Tests fail after patch"

Error:


terminal
❌ Test suite failed
Tests: 24 passed, 1 failed

Solutions:

▶

Review generated code:


bash
# View the patch that was applied
git diff HEAD

▶

Increase iterations (let voria refine):


bash
voria issue 42 --max-iterations 5

▶

Use different LLM (better quality):


bash
voria issue 42 --llm claude

▶

Check test output:


bash
# Detailed test failure info
pytest -vv  # Run locally

Cost & Token Issues

"Token budget exceeded"

Error:


terminal
BudgetExceededError: Daily budget of $5.00 exceeded

Solutions:

▶
Check spending:
```
bash
voria token info
```

▶

Increase budget:


bash
python3 -m voria.core.setup  # Reconfigure

▶

Use cheaper LLM:


bash
voria issue 42 --llm gemini  # Cheaper than OpenAI

▶

Skip iterations (don't refine):


bash
voria issue 42 --max-iterations 1

"High token usage"

Symptom:

▶Tokens used much higher than expected

Solutions:

▶

Reduce context:


bash
voria issue 42 --max-files 10 --exclude "tests/"

▶
Shorter prompts:
- ▶
  Customize prompts in
  terminal
  ~/.voria/prompts/
- ▶Remove unnecessary instructions

▶

Use faster model:


bash
voria issue 42 --model gpt-4-mini

Network Issues

"Connection timeout"

Error:


terminal
Connection timeout: Unable to reach api.openai.com

Solutions:

▶
Check internet connection:
```
bash
ping google.com
```

▶

Check DNS:


bash
nslookup api.openai.com

▶

Add network retry:


python
# In settings
voria_retry_count=3
voria_retry_delay=2

▶

Use VPN (if behind corporate proxy):


bash
# Configure system proxy
export HTTP_PROXY="http://proxy:8080"
export HTTPS_PROXY="https://proxy:8443"

"TLS certificate error"

Error:


terminal
SSL: CERTIFICATE_VERIFY_FAILED

Solutions (Development only):


bash
# Disable cert verification (unsafe!)
export INSECURE_SKIP_VERIFY=true
voria plan 1

# Better: Update CA certificates
# macOS
/usr/local/opt/openssl/bin/c_rehash

# Linux
sudo update-ca-certificates

Protocol Issues

"NDJSON protocol error"

Error:


terminal
JSON parsing error: extra data
PyErr_SetString: Protocol error

Solutions:

▶
Clear cache:
```
bash
rm -rf ~/.voria/
```

▶

Reinstall Python:


bash
cd python
pip uninstall voria
pip install -e .

▶

Check for corruption:


bash
# Test protocol manually
echo '{"command":"plan","issue_id":1}' | python3 -m voria.engine | head -1

"Process communication broken"

Symptoms:

▶Python subprocess crashes
▶No response from engine

Solutions:

▶

Kill stray processes:


bash
pkill -f voria.engine

▶

Check stderr for errors:


bash
voria -v plan 1 2>&1 | tail -20

▶

Test Python directly:


bash
python3 -m voria.engine  # See if it starts

Test Execution Issues

"Framework not detected"

Error:


terminal
Could not detect test framework

Solutions:

▶

Specify manually:


bash
voria issue 42 --test-cmd "pytest -v tests/"

▶

Check framework installed:


bash
pytest --version
# or
npm test -- --version

▶

Verify test directory exists:


bash
ls tests/
ls test/
# (check for capital T)

"Tests timeout"

Error:


terminal
Test execution timeout: Exceeded 300s

Solutions:

▶

Increase timeout:


bash
voria issue 42 --test-timeout 600

▶

Run tests individually:


bash
# Identify slow test
pytest --durations=10  # Show 10 slowest

▶

Skip slow tests:


bash
voria issue 42 --test-cmd "pytest -v -m 'not slow'"

Permission Issues

"Permission denied"

Error:


terminal
PermissionError: [Errno 13] Permission denied: '/repo/file.py'

Solutions:


bash
# Check permissions
ls -la /repo/file.py

# Fix permissions
chmod 644 /repo/file.py
chmod 755 /repo/

# Or run with adequate permissions
sudo voria issue 42  # ⚠️ Use cautiously

"Cannot write to backup directory"

Error:


terminal
PermissionError: ~/.voria/backups

Solutions:


bash
# Create backup directory
mkdir -p ~/.voria/backups

# Fix permissions
chmod 700 ~/.voria/

# Verify
ls -ld ~/.voria/

Output Issues

"Garbled output / strange characters"

Symptoms:

▶Unicode characters not displaying
▶Colored output broken

Solutions:


bash
# Force UTF-8
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# Disable colors (if terminal doesn't support)
voria --no-color plan 1

# Verify terminal encoding
locale

"No output at all"

Symptoms:

▶Command runs but shows nothing

Solutions:

▶
Use verbose flag:
```
bash
voria -v plan 1
```

▶

Check if running:


bash
# In another terminal
watch -n 1 'ps aux | grep voria'

▶

Check logs:


bash
tail -f ~/.voria/voria.log

Getting Help

Collect Debug Information


bash
# Generate debug bundle
mkdir voria-debug
cd voria-debug

# Collect versions
echo "Rust:" && rustc --version && cargo --version
echo "Python:" && python3 --version
echo "voria:" && ./target/release/voria --version

# Test setup
./target/release/voria --help > cli_help.txt
python3 -m voria.engine < /dev/null 2> engine.log

# System info
uname -a > system.txt
env | grep voria > voria_env.txt

# Create bundle
tar czf voria-debug.tar.gz *.txt *.log

# Upload to issue

Report an Issue

▶Search existing issues (might be solved)
▶
Create new issue with:
- ▶Error message (full text)
- ▶Commands you ran
- ▶Expected behavior
- ▶Actual behavior
- ▶Debug bundle (if complex)
▶Check GitHub Issues

Ask for Help

▶GitHub Discussions
▶Email: srizd449@gmail.com

See Also:

▶PERFORMANCE.md - Speed optimization
▶SECURITY.md - Security issues
▶DEVELOPMENT.md - Development setup issues

Join our WhatsApp Support Group: Click Here