spectral "OpenAPI ... errors" lint gate fails in CI

spectral lints your OpenAPI or AsyncAPI document against a ruleset. When rules flagged as errors are violated, spectral exits non-zero so the CI lint gate fails. The output lists each violation with its file, line, and rule.

What this error means

spectral prints a list of problems ending with a count of errors and warnings, and the job fails because at least one error-severity rule was violated.

openapi.yaml
 12:7  error  oas3-schema        "info" property must have required property "version"
 40:9  error  operation-description  Operation "description" must be present and non-empty
2 problems (2 errors, 0 warnings)

Common causes

The spec violates error-severity rules

Rules such as oas3-schema or operation-description are set to error, and the spec breaks them, so spectral fails the run.

No ruleset is resolved, or the wrong one is

Without a .spectral.yaml extending a base ruleset, spectral may apply defaults you did not intend, flagging or missing issues unexpectedly.

How to fix it

Fix the flagged rules or tune the ruleset

1. Read each error line: file, line, and rule name.
2. Fix the spec, or adjust the rule severity in .spectral.yaml if it does not apply.
3. Re-run the lint so the gate passes.

- run: npm install -g @stoplight/spectral-cli
- run: spectral lint openapi.yaml --ruleset .spectral.yaml

Define an explicit ruleset

Extend a known base ruleset and override severities intentionally so the gate is predictable.

extends: ["spectral:oas"]
rules:
  operation-description: error

How to prevent it

• Commit a .spectral.yaml so the ruleset is explicit and versioned.
• Run spectral in CI to keep the spec clean before it drifts.
• Set severities deliberately so the gate reflects your standards.

Related guides