serverless/serverless · error · ServerlessError

API_GATEWAY_EXTERNAL_EVENT_ROUTE_COLLISION

API_GATEWAY_EXTERNAL_EVENT_ROUTE_COLLISION

Error message

The route "${declaredRoutes[0]}" defined in this service uses the same API Gateway resource as "${contributedRoute}", which the mcp server "${externalEvent.functionName}" needs. Routes under an MCP server's path segment are reserved for that server. Rename the mcp server, or remove the conflicting http event.

What it means

Error "The route "${declaredRoutes[0]}" defined in this service uses the same API Gateway resource as "${contributedRoute}", which the mcp server "${externalEvent.functionName}" needs. Routes under an MCP server's path segment are reserved for that server. Rename the mcp server, or remove the conflicting http event." thrown in serverless/serverless.

Source

Thrown at packages/serverless/lib/plugins/aws/package/compile/events/api-gateway/lib/validate.js:339

        } else {
          declaredRoutesByResourceId.set(resourceId, [routeOf(event.http)])
        }
      }
      const contributedByResourceId = new Map()
      for (const externalEvent of this.externalHttpEvents) {
        if (!Object.hasOwn(serviceFunctions, externalEvent.functionName)) {
          throw new ServerlessError(
            `An internally contributed http event references the function "${externalEvent.functionName}", which is not defined in this service`,
            'API_GATEWAY_EXTERNAL_EVENT_UNKNOWN_FUNCTION',
            { stack: false },
          )
        }

        const resourceId = resourceIdOf(externalEvent.http)
        const contributedRoute = routeOf(externalEvent.http)
        const declaredRoutes = declaredRoutesByResourceId.get(resourceId)
        if (declaredRoutes) {
          throw new ServerlessError(
            `The route "${declaredRoutes[0]}" defined in this service uses the same API Gateway resource as "${contributedRoute}", which the mcp server "${externalEvent.functionName}" needs. Routes under an MCP server's path segment are reserved for that server. Rename the mcp server, or remove the conflicting http event.`,
            'API_GATEWAY_EXTERNAL_EVENT_ROUTE_COLLISION',
            { stack: false },
          )
        }

        const contributedMethod = this.getHttpMethod(externalEvent.http)
        const contributed = contributedByResourceId.get(resourceId)
        const conflicting = contributed?.find(
          (entry) =>
            entry.method === contributedMethod ||
            entry.method === 'any' ||
            contributedMethod === 'any',
        )
        if (conflicting) {
          throw new ServerlessError(
            `The mcp servers "${conflicting.functionName}" and "${externalEvent.functionName}" both need the API Gateway resource behind "${contributedRoute}" (their paths resolve to the same resource). Rename one of the mcp servers.`,
            'API_GATEWAY_EXTERNAL_EVENT_ROUTE_COLLISION',

View on GitHub (pinned to b9d7ea51c8)

Solutions

1. Rename the MCP server so its path segment no longer collides, or remove the conflicting http event route from your functions.

When it happens

Trigger: Thrown at packages/serverless/lib/plugins/aws/package/compile/events/api-gateway/lib/validate.js:339 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of serverless/serverless@b9d7ea51c8 (2026-08-13). Data as JSON: /api/errors/1084bea7b521dd9f. Report an issue: GitHub.