Troubleshooting
Find solutions to common issues when running Expanso Edge.
Quick Diagnostic Commands
# Check node status
expanso-cli node list
# Check job status
expanso-cli job list
# View execution details
expanso-cli execution list --state failed
expanso-cli execution list --state degraded
# Check job logs
expanso-cli job logs <job-id>
# Check edge process status
systemctl status expanso-edge
Common Issues
| Issue | Typical Symptoms |
|---|---|
| Permission Denied After Bootstrap | Can't write to /var/lib/expanso/edge or similar directories |
| Job Shows Failed But Completed | Job status shows "failed" but logs show successful completion |
| Pipeline Progress Lost After Restart | Pipeline restarts from the beginning after edge process restart |
| One-Shot Jobs Restart Unexpectedly | Batch jobs run again after edge restart when they shouldn't |
| Restart Events Not Tracked | Restarts don't show up in failure metrics or logs |
| Pipeline Stuck in Failed State | 409 CONFLICT errors when trying to redeploy a failed pipeline |
| Pipeline Stuck in Degraded State | Pipeline can't recover from degraded state automatically |
| Nodes Show Connected After Restart | Nodes appear connected but jobs don't start after orchestrator restart |
Next Steps
- Testing & Debugging - Validate and debug pipeline configurations
- Fleet Monitoring - Set up monitoring for your edge infrastructure
- Error Handling - Add retry logic and dead letter queues to pipelines