Troubleshooting syncs and diffs
Symptoms: syncs stuck or failing, errors after save, or no new changes when you expected them. Start in the dependency screen in the app; use the API only if you’re automating (Core resources).
1. Inspect sync history (UI)
- Open Dependencies and select the API.
- Find Sync history / Recent syncs / Jobs (wording varies).
- Open the latest run and read the stage (
fetch,parse, …) and any error message.
That usually tells you whether the problem is reachability (fetch), invalid OpenAPI (parse), or something else.
2. Fetch failures
| Symptom / cause | What to do |
|---|---|
| Unauthorized / 401/403 from vendor | Spec URL may need auth Intello can’t send—use a public spec or a proxy you control. |
| TLS / certificate errors | Confirm the URL works in a browser or curl from a machine outside your VPN. |
| Timeout | Vendor slow or blocking; try again later or use a CDN/stable host for the spec. |
| “Unsafe” or blocked URL | Intello blocks private IPs and similar—host the spec on public HTTPS or an approved proxy. |
Use Sync now on the dependency after fixing the URL. If a sync is already running, wait for it or cancel it from the UI when available.
3. Parse / normalize failures
- Paste the spec into a local OpenAPI validator; fix structural errors.
- Very large or unusual YAML can be rejected.
- Specs that rely on external
$reffetches may not parse fully—prefer a bundled document.
See OpenAPI specs.
4. Empty diffs
- First successful sync only creates a baseline—wait for a second successful sync after the vendor actually changes.
- Vendor may have republished the same contract (no semantic diff).
- Confirm you’re looking at the right dependency and spec URL.
5. Too many change rows
- Often one schema change touches many routes. Use the grouped change view and acknowledge by group when offered.
6. Paused / unhealthy dependency
After repeated failures, automatic syncs may pause. Fix the URL/spec issue, then run Sync now; successful runs restore health over time.
7. Developers: retry / cancel via API
POST /api/sync-jobs/:id/retry and POST /api/sync-jobs/:id/cancel match support runbooks when the UI isn’t enough.