SAM Doctor

ERROR REFERENCE

CORS preflight conflicts with an existing OPTIONS method

The template defines CORS twice: once through a Cors configuration that auto-creates preflight handlers, and once through an explicit OPTIONS method on the same path. API Gateway refuses the duplicate, and the deploy fails.

WHAT IT MEANS

What this error means

SAM's Cors property on AWS::Serverless::Api (or HttpApi) generates an OPTIONS preflight method for each configured path. If an event source or an OpenAPI definition also declares OPTIONS on that path — a common leftover from handling CORS manually before adopting the shorthand — the two definitions collide. The template says the same thing twice in incompatible ways; neither one is wrong alone.

FIX

How to fix it

  1. Pick one owner for preflight. Either keep the Cors configuration and delete the explicit OPTIONS event/method, or keep your handwritten OPTIONS handler and drop the Cors block. The shorthand is right for most APIs; the explicit method wins only when preflight needs custom logic.
  2. Check the OpenAPI definition too — an inline or referenced DefinitionBody can carry the duplicate options: entry even when no event source declares it.
  3. Redeploy and verify preflight with a browser or curl -X OPTIONS against the affected path — a 204 with the expected Access-Control-Allow-* headers.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor recognizes the duplicate-OPTIONS wording (medium confidence) in deploy logs. Runs locally; no AWS access, no log upload. 

python -m pip install sam-doctor
sam-doctor diagnose deployment.log --format markdown

RELATED