## TL;DR
Add the missing field the rule demands - usually a unique `operationId` on each operation - then rerun the linter until it reports no errors. Spectral's default OpenAPI ruleset requires operation IDs because code generators and doc tools key off them. If a rule does not fit your API, demote it to a warning in your ruleset instead of ignoring the lint output.

## The error
```text
"lint errors" on openapi document, operation missing
```

## Steps
1. Run the linter: `npx @stoplight/spectral-cli lint openapi.yaml`. Expected: a list of violations, each with a file, line number, rule name, and message.
2. For each operation flagged as missing an ID, open the operation and add a unique `operationId`, for example `listWidgets` for `GET /widgets`. Expected: every operation in the spec has an `operationId`.
3. For other errors (missing `info.description`, unused components, and similar), fix each as the message describes. Expected: you can explain what each remaining violation asks for.
4. Rerun the linter. Expected: it reports no results with a severity of error or higher.
5. If your pipeline treats warnings as failures too, open `.spectral.yaml` and set rules that do not apply to your API to `warn` or `off`, documenting why. Expected: the ruleset file reflects a deliberate choice per rule.

## Use this when
- `spectral lint` exits nonzero on an OpenAPI document.
- CI blocks docs generation or publishing on lint errors.
- Operations are flagged as missing `operationId` or similar required fields.

## Not for this skill when
- The failure is a Spectral crash or ruleset-load error rather than lint findings.
- You need to write a custom Spectral rule from scratch - that is ruleset authoring, not fixing findings.
- The spec fails in a different validator with no Spectral involvement.

## Variant phrasings
### spectral found errors in openapi spec
Same tool, same fix loop: run, read the rule messages, fix, rerun.
### operation must have operationId
This is the single most common Spectral finding on OpenAPI 3 specs. Same fix.
### openapi lint failed in CI
CI usually runs the linter with a fail-on-error severity. Reproduce locally with the same command and flags before pushing fixes.

## Why it happens
Spectral applies a ruleset of best practices to the spec, and several rules exist because downstream tools assume them: `operationId` feeds codegen method names and doc anchors, `info` fields feed rendered headers. Specs written by hand or merged from multiple sources routinely skip these fields, so the first lint run on a mature spec often surfaces a backlog.

## Edge cases
- Duplicate `operationId` values: the rule requires uniqueness too. A copy-pasted operation with the same ID fails the same rule a second time.
- Ruleset extension chains: if your ruleset extends another, a rule you turned off can come back via the parent. Check the resolved ruleset, not just your file.
- Spectral versions change rule names and severities. Pin the CLI version in CI so local and remote runs agree.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2w1wm--t_7edz76cruHUHQ