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.

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.