Common Issues

Solutions to the most frequently encountered problems when setting up and using SpecVault.

Spec upload fails with a parse error

Symptom

The dashboard shows an error like "Could not parse spec: invalid YAML" or "Not a valid OpenAPI document" after uploading.

Causes and fixes

• Indentation errors in YAML: YAML is sensitive to indentation. Validate your file with a linter (yamllint openapi.yaml) before uploading.
• JSON with trailing commas: Trailing commas are not valid JSON. Use a validator like python -m json.tool openapi.json to catch these.
• Missing openapi field: SpecVault requires an OpenAPI 3.x spec. Swagger 2.x (which uses the swagger key) is not supported. Upgrade your spec or use a converter.
• File too large: The upload size limit is 10 MB. If your spec is larger, consider serving it at a URL and using the spec_url publish method instead.

No breaking changes detected when I expect some

Symptom

You removed an endpoint or changed a required field but the diff shows no breaking changes.

Causes and fixes

• First version has no baseline: The very first spec published for a service has nothing to diff against. Breaking changes are only detected from the second version onwards.
• The change is additive: SpecVault only flags changes that break existing consumers — removing things or adding new required fields. Adding new optional fields, new endpoints, or new optional parameters is not a breaking change.
• The endpoint was already absent in the previous version: If the endpoint was never in the previous spec, removing it from the new spec has no effect. Check the version history to confirm the baseline.

Email alerts are not arriving

Symptom

Breaking changes are shown in the dashboard but subscribers are not receiving emails.

Causes and fixes

Email delivery is fully managed — there's no SMTP for you to configure. Check the following:

• Alert never dispatched: Open the audit log and look for an alert.sent event for that publish. If there's none, the publish likely contained no breaking changes (additive-only changes don't trigger alerts).
• Email in spam: Check the subscriber's spam or quarantine folder and allowlist the SpecVault sending domain.
• Subscriber not added: Verify the subscriber's email address appears in the Subscribers tab of the service. The alert fires only for listed subscribers.
• Wrong address: A typo in the subscriber address means the alert is sent but never lands. Confirm the spelling on the Subscribers tab.

API token returns 401 Unauthorized

Symptom

A curl or CI pipeline call returns 401 Unauthorized even though the token was just created.

Causes and fixes

• Token was revoked: Check the API Tokens page in the dashboard. If the token no longer appears, it was revoked and you need to create a new one.
• Authorization header format: The header must be exactly Authorization: Bearer <token>. A missing Bearer prefix (with a space) is the most common mistake.
• Extra whitespace or newline: When copying the token from the modal or CI secrets, trailing newlines or spaces can cause auth to fail. Check for invisible characters.
• Wrong SpecVault URL: Confirm you're hitting specvault.sentinelflux.in. A request to the wrong host will fail with a connection error or 404, not a 401.

Dashboard login fails

Symptom

The login page accepts your credentials but immediately redirects back to login.

Causes and fixes

• Wrong credentials: Use the email and password for your SpecVault account. If you've forgotten your password, use the reset link on the sign-in page.
• Session cookie issue: SpecVault uses a session cookie. If your browser is blocking cookies for the domain (e.g. in private/incognito mode with strict settings), login will not persist. Try a standard browser window.
• No account yet: If your team hasn't been granted access, request it at engage@sentinelflux.in.