User Guides
Troubleshooting
Diagnose common failures quickly with actionable checks and fixes.
Quick triage flow
When a problem appears, use this order:
- Confirm runtime config with
server_info. - Validate read path (
list_collections,read_document). - Validate permission scope (
OUTLINE_ALLOWED_ACTIONS). - Validate write paths with controlled test targets.
This order avoids debugging write behavior before basic auth and connectivity are stable.
Symptom and resolution table
| Symptom | Likely cause | Recommended fix |
|---|---|---|
PERMISSION_DENIED | Action not allowed in current profile | Update OUTLINE_ALLOWED_ACTIONS and restart process |
authentication_required or 401/403 | Invalid token, wrong endpoint, or restricted workspace token | Verify OUTLINE_API_KEY, OUTLINE_BASE_URL, and token scope |
CONFLICT_DETECTED in safe update | Revision changed after your last read | Re-read document, merge changes, retry with latest revision |
| Lease conflict | Another worker owns active lease | Wait/retry, or coordinate ownership reassignment |
| Export not downloadable yet | File operation still creating/uploading | Poll get_file_operation until state is complete |
| Missing optional tools | Capability probe disabled unavailable endpoints | Check probe status and endpoint availability |
| CI E2E skipped | OUTLINE_API_KEY secret not configured | Add GitHub secret and rerun workflow |
Practical diagnostics
Check effective runtime
Call server_info and confirm:
baseUrlallowedActionscapabilityProbeEnabled- lease strategy and TTL values
Check read before write
Use:
list_collectionssearch_documentsread_document
If these fail, resolve endpoint and auth issues first.
Check concurrency controls
For contested documents:
- inspect revision path (
read_document+safe_update_document) - inspect lease state (
get_active_document_lease)
Escalation checklist
When escalating internally, include:
- failing tool name and input shape
- current
OUTLINE_ALLOWED_ACTIONS - server info output (without secrets)
- exact error payload
- timestamp and target document or collection ID