Troubleshooting
Organized by symptom, since that is what you have when you arrive. Start with
arble server verify --all, which checks database, model backends, storage and sandbox in
one pass.
A run stops early with no obvious error
Almost always a denied capability. arble permissions audit --agent <id> --since 1h
shows the decision. Under a deny-by-default policy every capability must be granted explicitly.
The model is unavailable or runs queue forever
Test the backend directly, bypassing Arble. If the backend answers and Arble disagrees, the
configured base_url is wrong or egress is blocked from the runtime.
A connector stopped working
auth: expired means re-authorize. status: unreachable means DNS or egress.
The two need different fixes, and arble connectors status <name> distinguishes
them.
A tool is reported as unavailable
Run arble mcp health first. A server in error state contributes zero
tools, which the agent reports as the tool not existing.
Streams cut off at a fixed interval
A proxy, not Arble. Turn off response buffering and raise the read timeout above your longest run. This is the single most common self-hosted misconfiguration.
Everything is slow at once
Check database connections before hardware. Pool exhaustion presents as uniform slowness across unrelated operations.
Writes fail and runs break broadly
Storage. arble admin storage-usage shows what grew — usually files and
screenshots. Confirm the retention job is actually running; a leader-election failure stops it
silently.
Memory search returns nothing useful
If you changed embedding models, the index needs rebuilding — vectors from different models
are not comparable. Run arble memory reindex.
Filing a report
Include the request_id, the output of arble version, and the relevant
arble trace <agent> excerpt. Those three make most reports reproducible
immediately.