{"record":{"id":"f9d031894a5d9211","repo":"serverless/serverless","slug":"external-http-api-cors-config","errorCode":"EXTERNAL_HTTP_API_CORS_CONFIG","errorMessage":"Cannot setup CORS rules for externally configured HTTP API","messagePattern":"Cannot setup CORS rules for externally configured HTTP API","errorType":"exception","errorClass":"ServerlessError","httpStatus":null,"severity":"error","filePath":"packages/serverless/lib/plugins/aws/package/compile/events/http-api.js","lineNumber":456,"sourceCode":"Object.defineProperties(\n  HttpApiEvents.prototype,\n  memoizeeMethods({\n    resolveConfiguration: d(function () {\n      const routes = new Map()\n      const providerConfig = this.serverless.service.provider\n      const userConfig = providerConfig.httpApi || {}\n      this.config = {\n        routes,\n        id: userConfig.id,\n        metrics: userConfig.metrics || false,\n        disableDefaultEndpoint: userConfig.disableDefaultEndpoint,\n      }\n      let cors = null\n      let shouldFillCorsMethods = false\n      const userCors = userConfig.cors\n      if (userCors) {\n        if (userConfig.id) {\n          throw new ServerlessError(\n            'Cannot setup CORS rules for externally configured HTTP API',\n            'EXTERNAL_HTTP_API_CORS_CONFIG',\n          )\n        }\n        cors = this.config.cors = {}\n        if (userConfig.cors === true) {\n          Object.assign(cors, defaultCors)\n          shouldFillCorsMethods = true\n        } else {\n          cors.allowedOrigins = userCors.allowedOrigins\n            ? toSet(userCors.allowedOrigins)\n            : defaultCors.allowedOrigins\n          cors.allowedHeaders = userCors.allowedHeaders\n            ? toSet(userCors.allowedHeaders)\n            : defaultCors.allowedHeaders\n          if (userCors.allowedMethods)\n            cors.allowedMethods = toSet(userCors.allowedMethods)\n          else shouldFillCorsMethods = true","sourceCodeStart":438,"sourceCodeEnd":474,"githubUrl":"https://github.com/serverless/serverless/blob/b9d7ea51c8cce57cff1207964b9b71123673081f/packages/serverless/lib/plugins/aws/package/compile/events/http-api.js#L438-L474","documentation":"Thrown by the HTTP API (API Gateway v2) event plugin during configuration resolution. provider.httpApi.id marks the API as externally managed (created outside this stack), so the framework cannot attach or modify CORS settings on it. Setting provider.httpApi.cors alongside provider.httpApi.id is therefore rejected. CORS must be configured on the external API directly (AWS console, separate stack, or CDK).","triggerScenarios":"In serverless.yml, provider.httpApi.id is set to a string/CFN reference (e.g. an existing API ID) AND provider.httpApi.cors is truthy (either true, or an object with allowedOrigins etc.). The resolveConfiguration hook runs during package:compileEvents and the very first cors branch throws.","commonSituations":"Migrating an HTTP API to be externally managed (importing an existing API) while leaving the previously-working cors block in place. Copying a service config snippet that includes cors without noticing the id field is set. Splitting a monolith into a shared-API stack + function stacks.","solutions":["Remove the provider.httpApi.cors block from serverless.yml and configure CORS on the external HTTP API in its owning stack/CDK/Console.","If you want the framework to manage CORS, remove provider.httpApi.id so the API is created in this stack.","Double-check no computed value (variable/resolver) is silently producing a truthy cors when id is also set."],"exampleFix":"# before\nprovider:\n  httpApi:\n    id: abc123xyz\n    cors: true\n# after\nprovider:\n  httpApi:\n    id: abc123xyz\n# (configure CORS on the external API itself)","handlingStrategy":"validation","validationCode":"// Pre-flight check before deploy/package\nimport { readFileSync } from 'fs'\nconst cfg = require('js-yaml').load(readFileSync('serverless.yml','utf8'))\nconst h = cfg.provider?.httpApi ?? {}\nif (h.id && h.cors !== undefined) {\n  throw new Error('EXTERNAL_HTTP_API_CORS_CONFIG: remove httpApi.cors when httpApi.id is set')\n}","typeGuard":"// True when the API is externally managed and CORS must NOT be set\nconst isExternalHttpApiWithCorsConflict = (httpApi) =>\n  Boolean(httpApi?.id) && httpApi?.cors !== undefined && httpApi?.cors !== null","tryCatchPattern":null,"preventionTips":["Treat provider.httpApi.id as 'import-only': never pair it with cors/authorizers/logs blocks.","Run `sls print` after merging cross-stack configs to confirm no stray httpApi sub-keys remain.","Keep shared-API config in one place; consumers should only reference id."],"tags":["http-api","api-gateway","cors","config-validation","external-resource"],"backgroundTag":null,"analyzedSha":"b9d7ea51c8cce57cff1207964b9b71123673081f","analyzedAt":"2026-08-13T04:14:40.386Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}