My spec won't parse

If you have added an integration and the first sync failed with a parse error, or a previously functioning integration has begun returning parse failures, the underlying cause is generally a malformed or invalid OpenAPI document. Some failure modes can be recovered automatically; others require corrective action by the vendor.

Failure modes Intello recovers automatically

The spec-engine parser handles the following common defects without operator intervention:

• Specification version detection. OpenAPI 2.0 (Swagger), 3.0, and 3.1 documents are detected automatically and parsed with the appropriate loader. Swagger 2.0 documents are converted to OpenAPI 3.0 in memory before diffing.
• OpenAPI 3.1 compatibility. A pre-processing step adapts a small set of 3.1-only constructs (such as exclusiveMinimum as a number and JSON Schema description objects) so the strict 3.0 loader can accept them.
• Common encoding artefacts. UTF-8 byte-order marks and similar non-content prefixes are stripped before parsing.

If the document is otherwise valid and only requires one of these adjustments, the sync succeeds with no extra action.

Failure modes that require vendor action

The following conditions cannot be recovered without the vendor correcting the source document:

• Invalid JSON or YAML syntax — mismatched braces, unclosed strings, or malformed structure.
• Missing top-level info or paths sections, which OpenAPI requires.
• Unresolvable $ref chains, including circular references and references to hosts that the spec-engine cannot reach.
• Unsupported specification version — formats outside Swagger 2.0 / OpenAPI 3.0 / 3.1 are not handled.

When a sync hits one of these conditions, the dependency records a parse failure with a diagnostic message identifying the issue.

Recommended diagnostic steps

1. Open the specification URL in a browser. Confirm that the URL still returns the expected document. URLs occasionally redirect to login pages or 404 placeholders without obvious indication.
2. Validate the document against an external validator. Tools such as Swagger Editor provide line-level diagnostics. If the document fails external validation, the issue is on the vendor side.
3. Check for transient CDN issues. Some providers serve their specification through a CDN that occasionally returns stale or partial copies. Wait a short period and force a manual sync.
4. Report the issue to the vendor if the document is genuinely invalid. Most vendors respond promptly when given a specific validation error to reference.

While the parse failure persists, Intello continues to compare against the most recent successful snapshot — your historical baseline is not lost.

Library integrations

Library specifications are maintained by Intello. Persistent parse failures on a library integration are unusual; the underlying source is monitored and corrected as part of normal catalog maintenance, and the integration generally recovers without manual intervention.