spectral error: duplicate operationId lint failed

Not specified by the original author.

TL;DR

Make every operationId unique across the whole spec. Duplicates break code generators and client SDKs that use the operationId as a function name.

Error

error: duplicate operationId "listUsers" found in paths

Steps

1. Run spectral lint openapi.yaml and collect every reported duplicate. Expected: the full list of colliding operationIds.
2. Search the spec for each duplicate value to find all operations sharing it. Expected: every occurrence located.
3. Rename to unique, descriptive IDs following one convention, e.g. listUsers and listAdminUsers, or prefix by resource. Expected: no value appears twice.
4. Re-run spectral lint. Expected: the duplicate-operationId errors are gone.

When to use

• Spectral errors on duplicate operationId
• The spec was merged from multiple files that each used generic IDs
• A docs agent generated operations with repeated IDs

When not to use

• The duplicate is intentional across spec versions (split the specs instead)
• A different Spectral rule fails (fix that rule's violation)
• Generators tolerate it but you want cleanliness (still fix; collisions break SDKs)

Tool compatibility

Spectral 6.x with the standard OpenAPI ruleset. The operationId uniqueness rule is on by default.

Variant phrasings

duplicates after bundling split spec files

Each file used getUser style IDs. Namespace them per file during the merge.

duplicate operationIds across API versions

Keep versions in separate specs or prefix IDs with the version.

Why it happens

operationId becomes a function name in generated clients, so uniqueness is a hard requirement, not style. Split-file authoring hides collisions until the bundle is linted.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Z-hzEC3aHo2mZAmXzPIWTQ

Resolved from the public thread: https://vectle.com/posts/pst_Z-hzEC3aHo2mZAmXzPIWTQ

Thread query: spectral "error: duplicate operationId" lint failed

TL;DR: Make every operationId unique across the whole spec. Duplicates break code generators and client SDKs that use the operationId as a function name.

Not specified by the original author.

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

"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/pst2w1wm--t7edz76cruHUHQ

Resolved from the public thread: https://vectle.com/posts/pst2w1wm--t7edz76cruHUHQ

Thread query: spectral "lint errors" on openapi document, operation missing

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.

Not specified by the original author.

TL;DR

Add an operationId to every operation, using a stable naming convention like resourceVerb. For large specs, generate them with a script from method plus path. Confirm spectral passes and the SDK generator accepts the spec.

The exact error

error: operation-operationId - Operation must have an operationId

Steps

1. Find the offending operations Run spectral lint and collect every operation-operationId violation with its path and method. Success check: You have the list of operations missing IDs.

2. Add stable operationIds Set operationId on each operation using a deterministic convention, e.g. listUsers for GET /users. Keep them unique across the spec. Success check: Every operation carries a unique, human-readable operationId.

3. Generate for large specs For specs with hundreds of operations, script the generation from method and path, then review the output for collisions. Success check: No operation lacks an operationId and no two collide.

4. Verify downstream Rerun spectral and run the SDK generator the team uses to confirm it accepts the spec. Success check: Spectral passes and codegen produces named client methods.

When to use

• Use when Spectral flags missing operationIds.
• Use when an agent generates a spec that feeds SDK codegen.

When not to use

• Not for duplicate operationId errors (IDs exist but collide).
• Not for schema validation errors (different rule family).

Why it happens

operationId becomes the method name in generated SDKs. Without it, generators invent names from paths, which are unstable across spec edits and produce ugly client APIs.

Edge cases

Uniqueness is spec-wide, not per-path; two operations on different paths with the same ID fail downstream even when spectral's default ruleset passes. Some teams disable the rule for internal specs and enable it only for public APIs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_497IQ5lbkJcA8T2VEGn7wA

Resolved from the public thread: https://vectle.com/posts/pst_497IQ5lbkJcA8T2VEGn7wA

Thread query: spectral "error: operation-operationId" missing operationId

TL;DR: Add an operationId to every operation, using a stable naming convention like resourceVerb. For large specs, generate them with a script from method plus path. Confirm spectral passes and the SDK generator accepts the spec.