Troubleshooting

Server Won’t Start

Port already in use

ERROR: [Errno 10048] error while attempting to bind on address ('127.0.0.1', 8787)

Solution: Another process is using port 8787.

# Find what's using the port
Get-NetTCPConnection -LocalPort 8787 -ErrorAction SilentlyContinue |
    Select-Object OwningProcess |
    ForEach-Object { Get-Process -Id $_.OwningProcess }

# Kill the process if it's a stale Provara instance
Get-Process uvicorn -ErrorAction SilentlyContinue | Stop-Process -Force

Or change the port:

AGENT_HUB_PORT=8788

Module not found

ModuleNotFoundError: No module named 'src.server'

Solution: Run from the project root directory, or set AGENT_HUB_ROOT:

cd C:\path\to\provara
uv run uvicorn src.server.main:app --host 127.0.0.1 --port 8787

Missing dependencies

ModuleNotFoundError: No module named 'fastapi'

Solution: Sync dependencies:

uv sync

Authentication Issues

401 Unauthorized

{"detail": "Invalid or missing token"}

Causes:

1. Token not set in request header
2. Token doesn’t match server’s token
3. Header name is wrong (must be X-Agent-Token)

Fix:

# Check what token the server is using
Get-Content runtime\agent_hub_token.txt

# Verify your request
$token = Get-Content runtime\agent_hub_token.txt
Invoke-RestMethod http://127.0.0.1:8787/pending `
    -Headers @{ "X-Agent-Token" = $token }

For the Python SDK:

# Ensure environment variable is set
$env:AGENT_HUB_TOKEN = Get-Content runtime\agent_hub_token.txt

Policy Blocks

Command not allowed

{"detail": {"error": "policy_blocked", "reason": "not_allowed:my-command"}}

Meaning: The command doesn’t match any allow pattern.

Check which patterns exist:

from src.server.exec.policy import ALLOW
for i, p in enumerate(ALLOW):
    print(f"[{i}] {p}")

Options:

1. Modify the command to match an existing pattern
2. Add a new allow pattern to policy.py
3. Use a workspace script instead

Command denied by pattern

{"detail": {"error": "policy_blocked", "reason": "deny:\\b(Remove-Item|del)"}}

Meaning: The command matches a deny pattern. Deny patterns always take priority over allow patterns.

Caution

Do not remove deny patterns to work around blocks. They exist to prevent dangerous operations. Instead, use workspace scripts or modify your approach.

CWD blocked

{"detail": {"error": "policy_blocked", "reason": "cwd_blocked:C:\\Windows"}}

Meaning: The working directory is outside the project root.

Fix: Don’t specify a cwd, or ensure it’s under the project directory.

Connection Issues

Cannot reach server

httpx.ConnectError: [Errno 10061] Connect call failed

Checklist:

1. Is the server running?

   Test-NetConnection 127.0.0.1 -Port 8787

2. Is it on the right port?

   $env:AGENT_HUB_PORT  # Check configured port

3. Is a firewall blocking it?

   Get-NetFirewallRule | Where-Object { $_.DisplayName -match "uvicorn" }

Rate limited

{"error": "Rate limit exceeded", "retry_after_seconds": 60}

Solution: Wait for the rate limit window to expire, or increase the limit:

AGENT_HUB_RATE_LIMIT_REQUESTS=200
AGENT_HUB_RATE_LIMIT_WINDOW_SECONDS=60

Execution Issues

Command times out

{"stderr": "timeout after 60s", "exit_code": -1}

Solution: Increase the timeout when queueing:

plan(command="long-running-command", timeout_s=600)  # 10 minutes

Maximum allowed: 3600 seconds (1 hour).

PowerShell execution policy

File cannot be loaded because running scripts is disabled on this system.

Solution: Provara already uses -ExecutionPolicy Bypass, but if you’re running scripts manually:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Empty stdout

Some commands produce output but it appears empty. This can happen with:

• Commands that write to the host instead of stdout
• Format commands that output objects not strings

Fix: Pipe to Out-String:

Get-Process python | Out-String

Data Issues

Stale pending commands

Old commands accumulating in the pending queue:

# View old pending items
Get-ChildItem runtime\pending -Filter "*.json" |
    Sort-Object LastWriteTime |
    Select-Object Name, LastWriteTime

# Remove items older than 24 hours
Get-ChildItem runtime\pending -Filter "*.json" |
    Where-Object { $_.LastWriteTime -lt (Get-Date).AddHours(-24) } |
    Remove-Item

Audit log growing too large

The audit log is append-only. Rotate it periodically:

# Rotate audit log
$date = Get-Date -Format "yyyyMMdd"
Move-Item runtime\audit.log "runtime\audit_$date.log"
# Server will create a new audit.log on next write

Getting Help

If you’re stuck:

1. Check the server logs (stdout) for error details
2. Set AGENT_HUB_LOG_LEVEL=DEBUG for verbose output
3. Check the /health endpoint for system status
4. Review runtime/audit.log for recent activity
5. Open an issue on GitHub