Troubleshooting guide
Use this guide to resolve frequent issues quickly. Most commands support --verbose for expanded diagnostics.
Quick checks
- Run
cerulion status to confirm active profile, project link, and transports.
- Add
--output json to inspect exact error codes and remediation hints.
- Use
CERULION_LOG=debug for verbose logs when filing support tickets.
Common issues
| Symptom | Likely cause | Fix |
|---|
AUTH_REQUIRED on any command | Missing or expired credentials. | cerulion auth login --browser or --token <PAT> in CI. |
| Schema validation fails after a field change | Breaking type change or missing default. | Add defaults, bump version, or use --allow-breaking only in dev. |
Transport unavailable: iceoryx2 | Kernel shared-memory limits or missing daemon. | Restart the iceoryx daemon and check /dev/shm limits; fall back to transport.local: memory temporarily. |
| Slow builds on CI | Re-downloading dependencies each run. | Cache ~/.cache/cerulion and the downloaded CLI binary between runs. |
Logs not streaming in cerulion run local | Network blocked or wrong profile. | Ensure the profile points to local endpoints; retry with --env local. |
verify fails after upgrade | Tampered download or MITM protection triggered. | Re-download from trusted network; verify checksums via cerulion verify --path ./cerulion. |
Collecting diagnostics
cerulion status --output json > /tmp/cerulion-status.json
cerulion logs --env staging --node ingestion --since 10m --output json > /tmp/cerulion-logs.json
cerulion metrics --env staging --since 10m --output json > /tmp/cerulion-metrics.json
Resetting local state
cerulion auth logout
rm -rf ~/.config/cerulion
cerulion auth login --browser
Removing the config directory deletes profiles and cached credentials. Back up profile files if you manage multiple environments.
