Troubleshooting

General Tips

Always configure logging as described in the installation guide to aid troubleshooting.
For any issue not covered here, contact support team or raise a GitLab issue.

The data sync process in ipfabric_netbox consists of several steps. Below are common issues and solutions for each stage:

Issue: NetBox Job does not start
- Cause: RQ workers are down.
- Symptom: Job status remains at Pending.
- Solution: Ensure RQ workers are running. Restart them if necessary.
Issue: Cannot connect to IPFabric instance
- Cause: Network issues, misconfiguration, or SSL certificate validation errors.
- Symptom: Sync times out with connection errors in UI.
- Solution: Check network connectivity, verify configuration, and ensure SSL certificates are valid.

Issue: Data not synced or merged
- Cause: Snapshots not loaded, or merge step forgotten.
- Symptom: Data missing after sync, or incomplete objects in NetBox.
- Solution: Always load snapshots before syncing. After sync, ensure you run the merge step.
Issue: Sync job stuck on Running state
- Cause: Low RQ_DEFAULT_TIMEOUT or out-of-memory (OOM).
- Symptom:
  - Timeout: JobTimeoutException in Ingestion Issues tab or logs (must be configured per installation guide).
  - OOM: Check journalctl for OOM errors by timestamp.
  - In both cases, Job logs in UI could be missing.
- Solution:
  - Increase RQ_DEFAULT_TIMEOUT in your configuration.
  - Ensure your system has enough memory for large sync jobs.
  - Review logs and journalctl for error details.

Issue: No logs or progress indication in UI
- Symptom: Merge stage shows no UI logs; progress is unclear.
- Expected: Merge should take roughly half the time of the sync stage. For large datasets, both sync and merge can take hours.
- Solution: Check backend logs for errors or progress. If issues occur, they will be shown in the logs.