Forem: Marco Gonzalez

API Gateway + Lambda authorizer + Lambda proxy integration failure modes

Marco Gonzalez — Mon, 26 May 2025 05:14:29 +0000

In order to properly troubleshoot issues in serverless architectures built with API Gateway and AWS Lambda, it's useful to be aware of API Gateway's default failure modes when configured with a Lambda authorizer and a Lambda proxy integration.

Note: This post refers to API Gateway's default failure modes because Gateway responses allow to customize HTTP responses sent by API Gateway for certain failures.

A Lambda authorizer must return a Lambda authorizer output with at least a policyDocument (other fields are optional) in to evaluate the request against.
The policy evaluation can have one of the following results:

Result	Description	Response status code	Response body
`ALLOW`	The HTTP request matches at least one `ALLOW` statement in the policy and does not match any `DENY` statements.	(Depends on API Gateway integration)	(Depends on API Gateway integration)
`EXPLICIT_DENY`	The HTTP request matches at least one `DENY` statement in the policy.	`403`	`{ "Message": "User is not authorized to access this resource with an explicit deny" }`
`IMPLICIT_DENY`	The HTTP request does not match any statements in the policy.	`403`	`{ "Message": "User is not authorized to access this resource" }`

Note: There are two types of Lambda authorizers: REQUEST and TOKEN. This post focuses on REQUEST Lambda authorizers, so your mileage may vary for TOKEN Lambda authorizers.

An HTTP request sent to an API Gateway instance configured with a REQUEST Lambda authorizer and a Lambda proxy integration can fail due to one or more of the following reasons:

Error	Description	Lambda error	APIGW status code	APIGW body
`AUTHORIZER_APIGW_ID_SRC_MISSING`	The request has a missing, null or empty `REQUEST` Lambda authorizer identity source value.	-	`401`	`{ "message": "Unauthorized" }`
`AUTHORIZER_APIGW_TIMEOUT`	API Gateway times out while waiting for the Lambda authorizer invocation to complete.	`No`	`500`	`{ "message": null }`
`AUTHORIZER_ERROR_OTHER`	The Lambda authorizer returns an invocation error with `errorMessage` set to anything other than `"Unauthorized"`.	`Yes`	`500`	`{ "message": null }`
`AUTHORIZER_ERROR_UNAUTHORIZED`	The Lambda authorizer returns an invocation error with `errorMessage` set to `"Unauthorized"`.	`Yes`	`401`	`{ "message": "Unauthorized" }`
`AUTHORIZER_INVOKE_DENIED`	API Gateway or the configured API Gateway IAM Role is not authorized to invoke the Lambda authorizer.	-	`500`	`{ "message": null }`
`AUTHORIZER_LAMBDA_TIMEOUT`	The Lambda function execution exceeds the configured Lambda timeout.	`Yes`	`500`	`{ "message": null }`
`AUTHORIZER_RESPONSE_INVALID`	The Lambda authorizer returns an invocation response that does not conform to the Lambda authorizer output.	`No`	`500`	`{ "message": null }`
`PROXY_INTEG_APIGW_TIMEOUT`	API Gateway integration timeout elapses before the Lambda proxy integration invocation finishes.	`No`	`504`	`{ "message": "Endpoint request timed out" }`
`PROXY_INTEG_ERROR`	The Lambda proxy integration returns an invocation error.	`Yes`	`502`	`{ "message": "Internal server error" }`
`PROXY_INTEG_INVOKE_DENIED`	API Gateway or the configured API Gateway IAM Role is not authorized to invoke the Lambda proxy integration.	-	`500`	`{ "message": "Internal server error" }`
`PROXY_INTEG_LAMBDA_TIMEOUT`	The Lambda proxy integration exceeds the configured Lambda timeout before the integration timeout elapses.	`Yes`	`502`	`{ "message": "Internal server error" }`
`PROXY_INTEG_RESPONSE_INVALID`	The Lambda proxy integration returns an invocation response that does not conform to the Lambda proxy output.	`No`	`502`	`{ "message": "Internal server error" }`

Note: API Gateway can invoke a Lambda function directly or through an API Gateway IAM Role.
In order to prevent *_INVOKE_DENIED errors, if don't use a role, make sure to properly configure a resource-based policy allowing API Gateway to invoke each Lambda function.

Warning: When a Lambda authorizer returns an "Unauthorized" invocation error, even though API Gateway responds with a 401, the Lambda service increments the Lambda Errors metric which may trigger a CloudWatch "false alarm".

Warning: The AUTHORIZER_APIGW_TIMEOUT timeout cannot be explicitly configured and it's not publicly documented.
However, manual tests of this have determined that it's 30 seconds.

As a result, you should configure the Lambda authorizer's Lambda timeout to be 29 seconds or less so that:

The Lambda authorizer does not continue executing (and getting charged) in order to produce a response that would be ignored by API Gateway.
Lambda authorizer timeouts can be unambiguously distinguished from other failures.

Node.js and esbuild: beware of mixing cjs and esm

Marco Gonzalez — Fri, 13 Dec 2024 17:00:29 +0000

TL;DR

When using esbuild to bundle code with --platform=node that depends on npm packages with a mixture of cjs and esm entry points, use the following rule of thumb:

When using --bundle, set --format to cjs. This will work in all cases except for esm modules with top-level await.
- --format=esm can be used but requires a polyfill such as this one.
When using --packages=external, set --format to esm.

If you're wondering about the difference between cjs and esm, take a look at Node.js: A brief history of cjs, bundlers, and esm.

Symptom

When executing esbuild bundled code with --platform=node you may have come across one of the following runtime errors:

Error: Dynamic require of "<module_name>" is not supported

Error [ERR_REQUIRE_ESM]: require() of ES Module (...) from (...) not supported.
Instead change the require of (...) in (...) to a dynamic import() which is available in all CommonJS modules.

Cause

This is because of one of the following limitations:

esbuild's esm to cjs (and vice-versa) transformations.
Node.js cjs/esm interoperability.

Analysis

esbuild has limited transformation capabilities between esm and cjs. Additionally, some scenarios while supported by esbuild are not supported by Node.js itself. As of esbuild@0.24.0, the following table summarizes what's supported:

Format	Scenario	Supported?
`cjs`	static `import`	Yes
`cjs`	dynamic `import()`	Yes
`cjs`	top-level `await`	No
`cjs`	`--packages=external` of `esm` entry point	No*
`esm`	`require()` of user modules**	Yes***
`esm`	`require()` of `node:*` modules	No****
`esm`	`--packages=external` of `cjs` entry point	Yes

* Supported by esbuild but not by Node.js

** Refers to npm packages or relative path files.

*** User modules are supported with some caveats: __dirname and __filename are not supported without a polyfill.

**** node:* modules can be supported with the same polyfill.

What follows is a detailed description of these scenarios without the use of any polyfills:

npm packages

We'll use the following example npm packages:

static-import

esm module with a static import:

import { version } from "node:process";

export function getVersion() {
  return version;
}

dynamic-import

esm module with a dynamic import() within an async function:

export async function getVersion() {
  const { version } = await import("node:process");
  return version;
}

top-level-await

esm module with a dynamic import() and a top-level await:

const { version } = await import("node:process");

export function getVersion() {
  return version;
}

require

cjs module with a require() invocation:

const { version } = require("node:process");

exports.getVersion = function() {
  return version;
}

--format=cjs

We'll run esbuild with the following arguments:

esbuild --bundle --format=cjs --platform=node --outfile=bundle.cjs src/main.js

and the following code:

import { getVersion } from "{npm-package}";

(async () => {
  // version can be `string` or `Promise<string>`
  const version = await getVersion();

  console.log(version);
})();

static import

Produces the following which runs just fine:

// node_modules/static-import/index.js
var import_node_process = require("node:process");
function getVersion() {
  return import_node_process.version;
}

// src/main.js
(async () => {
  const version2 = await getVersion();
  console.log(version2);
})();

dynamic import()

Produces the following which runs just fine:

// (...esbuild auto-generated helpers...)

// node_modules/dynamic-import/index.js
async function getVersion() {
  const { version } = await import("node:process");
  return version;
}

// src/main.js
(async () => {
  const version = await getVersion();
  console.log(version);
})();

Notice how the dynamic import() is not transformed to a require() because it's also allowed in cjs modules.

top-level await

esbuild fails with the following error:

[ERROR] Top-level await is currently not supported with the "cjs" output format

    node_modules/top-level-await/index.js:1:20:
      1 │ const { version } = await import("node:process");
        ╵                     ~~~~~

--packages=external

Using --packages=external succeeds with all npm packages:

esbuild --packages=external --format=cjs --platform=node --outfile=bundle.cjs src/main.js

produces:

var npm_package_import = require("{npm-package}");
(async () => {
  const version = await (0, npm_package_import.getVersion)();
  console.log(version);
})();

However, they all fail to run because Nodes.js doesn't allow cjs modules to import esm modules:

/(...)/bundle.cjs:1
var import_static_import = require("static-import");
                           ^

Error [ERR_REQUIRE_ESM]: require() of ES Module /(...)/node_modules/static-import/index.js from /(...)/bundle.cjs not supported.
Instead change the require of index.js in /(...)/bundle.cjs to a dynamic import() which is available in all CommonJS modules.

--format=esm

We'll now run esbuild with the following arguments:

esbuild --bundle --format=esm --platform=node --outfile=bundle.mjs src/main.js

require() of user modules

src/main.js

const { getVersion } = require("static-import");

console.log(getVersion());

produces the following which runs just fine:

// (...esbuild auto-generated helpers...)

// node_modules/static-import/index.js
var static_import_exports = {};
__export(static_import_exports, {
  getVersion: () => getVersion
});
import { version } from "node:process";
function getVersion() {
  return version;
}
var init_static_import = __esm({
  "node_modules/static-import/index.js"() {
  }
});

// src/main.js
var { getVersion: getVersion2 } = (init_static_import(), __toCommonJS(static_import_exports));
console.log(getVersion2());

require() of node:* modules

src/main.js

import { getVersion } from "require";

console.log(getVersion());

produces the following:

// (...esbuild auto-generated helpers...)

var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
}) : x)(function(x) {
  if (typeof require !== "undefined") return require.apply(this, arguments);
  throw Error('Dynamic require of "' + x + '" is not supported');
});

// (...esbuild auto-generated helpers...)

// node_modules/require/index.js
var require_require = __commonJS({
  "node_modules/require/index.js"(exports) {
    var { version } = __require("node:process");
    exports.getVersion = function() {
      return version;
    };
  }
});

// src/main.js
var import_require = __toESM(require_require());
console.log((0, import_require.getVersion)());

However, it fails to run:

Error: Dynamic require of "node:process" is not supported

--packages=external

Using --packages=external succeeds with all npm packages, including those with cjs entry points. For example:

esbuild --packages=external --format=esm --platform=node --outfile=bundle.mjs src/main.js

with:

src/index.js

import { getVersion } from "require";

console.log(getVersion());

produces a nearly-verbatim output which runs just fine because esm modules can import npm packages with cjs entry points:

import { getVersion } from "require";
console.log(getVersion());

Conclusion

I hope you find this post useful to troubleshoot esbuild outputs now and in the future. Let me know your thoughts below!

Node.js: A brief history of cjs, bundlers, and esm

Marco Gonzalez — Thu, 12 Dec 2024 23:12:37 +0000

Introduction

If you're a Node.js developer, you've probably heard of cjs and esm modules but may be unsure why there's two and how do these coexist in Node.js applications. This blogpost will briefly walk you through the history of JavaScript modules in Node.js (with examples 🙂) so you can feel more confident when dealing with these concepts.

The global scope

Initially JavaScript only had a global scope were all members were declared. This was problematic when sharing code because two independent files may use the same name for a member. For example:

greet-1.js

function greet(name) {
  return `Hello ${name}!`;
}

greet-2.js

var greet = "...";

index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Collision example</title>
  </head>
  <body>
    <!-- After this script, `greet` is a function -->
    <script src="greet-1.js"></script>

    <!-- After this script, `greet` is a string -->
    <script src="greet-2.js"></script>

    <script>
        // TypeError: "greet" is not a function
        greet();
    </script>
  </body>
</html>

CommonJS modules

Node.js formally introduced the concept of JavaScript modules with CommonJS (also known as cjs). This solved the collision problem of shared global scopes since developers could decide what to export (via module.exports) and import (via require()). For example:

src/greet.js

// this remains "private"
const GREETING_PREFIX = "Hello";

// this will be exported
function greet(name) {
  return `${GREETING_PREFIX} ${name}!`;
}

// `exports` is a shortcut to `module.exports`
exports.greet = greet;

src/main.js

// notice the `.js` suffix is missing
const { greet } = require("./greet");

// logs: Hello Alice!
console.log(greet("Alice"));

npm packages

Node.js development exploded in popularity thanks to npm packages which allowed developers to publish and consume re-usable JavaScript code. npm packages get installed in a node_modules folder by default. The package.json file present in all npm packages is especially important because it can indicate Node.js which file is the entry point via the "main" property. For example:

node_modules/greeter/package.json

{
  "name": "greeter",
  "main": "./entry-point.js"
  // ...
}

node_modules/greeter/entry-point.js

module.exports = {
  greet(name) {
    return `Hello ${name}!`;
  }
};

src/main.js

// notice there's no relative path (e.g. `./`)
const { greet } = require("greeter");

// logs: Hello Bob!
console.log(greet("Bob"));

Bundlers

npm packages dramatically sped up the productivity of developers by being able to leverage other developers' work. However, it had a major disadvantage: cjs was not compatible with web browsers. To solve this problem, the concept of bundlers was born. browserify was the first bundler which essentially worked by traversing an entry point and "bundling" all the require()-ed code into a single .js file compatible with web browsers. As time went on, other bundlers with additional features and differentiators were introduced. Most notably webpack, parcel, rollup, esbuild and vite (in chronological order).

ECMAScript modules

As Node.js and cjs modules became mainstream, the ECMAScript specification maintainers decided to include the module concept. This is why native JavaScript modules are also known as ESModules or esm (short for ECMAScript modules).

esm defines new keywords and syntax for exporting and importing members as well as introduces new concepts like default export. Over time, esm modules gained new capabilities like dynamic import() and top-level await. For example:

src/greet.js

// this remains "private"
const GREETING_PREFIX = "Hello";

// this will be exported
export function greet(name) {
  return `${GREETING_PREFIX} ${name}!`;
}

src/part.js

// default export: new concept
export default function part(name) {
  return `Goodbye ${name}!`;
}

src/main.js

// notice the `.js` suffix is required
import part from "./part.js";

// dynamic import: new capability
// top-level await: new capability
const { greet } = await import("./greet.js");

// logs: Hello Alice!
console.log(greet("Alice"));

// logs: Bye Bob!
console.log(part("Bob"));

Over time, esm became widely adopted by developers thanks to bundlers and languages like TypeScript since they are capable of transforming esm syntax into cjs.

Node.js cjs/esm interoperability

Due to growing demand, Node.js officially added support for esm in version 12.x. Backwards compatibility with cjs was achieved as follows:

Node.js interprets .js files as cjs modules unless the package.json sets the "type" property to "module".
Node.js interprets .cjs files as cjs modules.
Node.js interprets .mjs files as esm modules.

When it comes to npm package compatibility, esm modules can import npm packages with cjs and esm entry points. However, the opposite comes with some caveats. Take the following example:

node_modules/cjs/package.json

{
  "name": "cjs",
  "main": "./entry.js"
}

node_modules/cjs/entry.js

module.exports = {
  value: "cjs"
};

node_modules/esm/package.json

{
  "name": "esm",
  "type": "module",
  "main": "./entry.js"
}

node_modules/esm/entry.js

export default {
  value: "esm"
};

The following runs just fine:

src/main.mjs

import cjs from "cjs";
import esm from "esm";

// logs: { value: 'cjs' }
console.log(cjs);

// logs: { value: 'esm' }
console.log(esm);

However, the following fails to run:

src/main.cjs

// OK
const cjs = require("cjs");
// Error [ERR_REQUIRE_ESM]:
// require() of ES Module (...)/node_modules/esm/entry.js
// from (...)/src/main.cjs not supported
const esm = require("esm");

console.log(cjs);
console.log(esm);

The reason why this is not allowed is because esm modules allow top-level await whereas the require() function is synchronous. The code could be re-written to use dynamic import(), but since it returns a Promise it forces to have something like the following:

src/main.cjs

(async () => {
  const { default: cjs } = await import("cjs");
  const { default: esm } = await import("esm");

  // logs: { value: 'cjs' }
  console.log(cjs);

  // logs: { value: 'esm' }
  console.log(esm);
})();

To mitigate this compatibility problem, some npm packages expose both cjs and mjs entry points by leveraging package.json's "exports" property with conditional exports. For example:

node_modules/esm/entry.cjs:

// usually this would be auto-generated by a tool
module.exports = {
  value: "esm"
};

node_modules/esm/package.json:

{
  "name": "esm",
  "type": "module",
  "main": "./entry.cjs",
  "exports": {
    "import": "./entry.js",
    "require": "./entry.cjs"
  }
}

Notice how "main" points to the cjs version for backwards compatibility with Node.js versions that do not support the "exports" property.

Conclusion

That's (almost) all you need to know about cjs and esm modules (as of Dec/2024 🙃). Let me know your thoughts below!

Type-safe EventTarget subclasses in TypeScript

Marco Gonzalez — Fri, 27 Jan 2023 20:40:28 +0000

Problem

I was surprised when I found out that TypeScript does not have a type-safe EventTarget interface definition:

interface EventTarget {
  addEventListener(
    type: string,
    callback: EventListenerOrEventListenerObject | null,
    options?: AddEventListenerOptions | boolean
  ): void;

  dispatchEvent(event: Event): boolean;

  removeEventListener(
    type: string,
    callback: EventListenerOrEventListenerObject | null,
    options?: EventListenerOptions | boolean
  ): void;
}

This makes it difficult to create type-safe APIs that extend EventTarget. Take the following example:

// API definition
interface MediaPlayerEvent {
  readonly time: number;
}

class MediaPlayer extends EventTarget {
  play() {
    // ...
    this.dispatchMediaPlayerEvent("play", time);
  }

  stop() {
    // ...
    this.dispatchMediaPlayerEvent("stop", time);
  }

  private dispatchMediaPlayerEvent(type: string, time: number) {
    this.dispatchEvent(
      new CustomEvent(eventType, { detail: { time } });
    );
  }
}

// API consumer
const player = new MediaPlayer(/* ... */);
player.addEventListener("play", (e) => {
  // compilation error: `e` is of type `Event`
  const { time } = e.detail;
});

How can the API consumers know which events are available and corresponding event types from a TypeScript IDE?

Solution

We can use the following type definitions to solve our problem:

type TypedEventTarget<EventMap extends object> =
  { new (): IntermediateEventTarget<EventMap>; };

// internal helper type
interface IntermediateEventTarget<EventMap> extends EventTarget {
  addEventListener<K extends keyof EventMap>(
    type: K,
    callback: (
      event: EventMap[K] extends Event ? EventMap[K] : never
    ) => EventMap[K] extends Event ? void : never,
    options?: boolean | AddEventListenerOptions
  ): void;

  addEventListener(
    type: string,
    callback: EventListenerOrEventListenerObject | null,
    options?: EventListenerOptions | boolean
  ): void;
}

Then when can re-define the MediaPlayer class as follows:

class MediaPlayer extends (EventTarget as TypedEventTarget<{
  play: CustomEvent<MediaPlayerEvent>;
  stop: CustomEvent<MediaPlayerEvent>;
}>) {
  // ...
}

Voilà! We have type safety:

player.addEventListener("play", (e) => {
  // it works now!
  const { time } = e.detail;
});

player.addEventListener("other", (e) => {
  // this also works, but `e` is of type: `Event`
});

Limitations

All properties in the EventMap of TypedEventTarget<EventMap> must implement the Event interface since EventTarget can only dispatch objects that implement it. In other words, this should not compile:

class MediaPlayer2 extends (EventTarget as TypedEventTarget<{
  play: MediaPlayerEvent;
  stop: MediaPlayerEvent;
}> {
  // ...
}

However tsc will not complain. This is mitigated by making it impossible to listen to such events:

const player = new MediaPlayer2(/* ... */);

player.addEventListener("play", e => {
  // compilation error:
  // `e` and return type are of type: `never`
});

We could prevent the class from compiling by replacing unknown with Event in the generic constraint (i.e. EventMap extends Record<string, unknown>), however this has the unfortunate side-effect of removing the event name suggestions in Visual Studio Code IntelliSense so I opted for the latter.

Finally, it's worth noting that given the API design of EventTarget, there doesn't seem to be a way to add type-safety to event dispatching.

If you have a way to overcome any of these limitations, let me know in the comments section!

Posts that inspired this one

This post was inspired by RJ Zaworski's and James Garbutt's posts. Credits to them for the initial ideas! That being said, the solutions in those posts have some shortcomings addressed by the solution on this post. For example RJ's does not compile in strict mode and has the runtime overhead of a new class. On the other hand, James' does not prevent EventMap from containing non-Event fields.