ERR_REQUIRE_ASYNC_MODULE when deploying with Node.js v22.12.0

[gustavopch]

[REQUIRED] Environment info

firebase-tools: 13.28.0

Platform: GitHub Actions • Ubuntu 24.04.1 LTS (list of included software) • Node.js v22.12.0

[REQUIRED] Test case

While I don't have an MCVE at the moment, I believe the cause may be this specific line, which seems to be the only require() call in firebase-functions:
https://github.com/firebase/firebase-functions/blob/9ed934d3dc4c2c257ac1968a65f6913c73ca779f/src/runtime/loader.ts#L49.

[REQUIRED] Steps to reproduce

Try to deploy anything to Firebase Functions using Node.js v22.12.0 with "type": "module" in package.json. I was able to deploy just yesterday via GitHub Actions (it ran with Node.js v22.11.0). In fact, Node.js v22.12.0's changelog lists this "notable change": require(esm) is now enabled by default, which seems related to the error shown in the logs below.

[REQUIRED] Expected behavior

Should not crash.

[REQUIRED] Actual behavior

Run yarn firebase deploy \
  yarn firebase deploy \
    --message "$(date +%Y-%m-%d)-$(git rev-parse --short HEAD)" \
    --force
  shell: /usr/bin/bash -e {0}
  env:
    FIREBASE_TOKEN: ***
    FORCE_COLOR: 3
    npm_config_cache: /home/runner/.npm
yarn run v1.22.22
$ /home/runner/work/<omitted>/node_modules/.bin/firebase deploy --message 2024-12-11-b8e1fafe --force
(node:1930) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
⚠  Authenticating with `FIREBASE_TOKEN` is deprecated and will be removed in a future major version of `firebase-tools`. Instead, use a service account key with `GOOGLE_APPLICATION_CREDENTIALS`: https://cloud.google.com/docs/authentication/getting-started
(node:1930) [DEP0044] DeprecationWarning: The `util.isArray` API is deprecated. Please use `Array.isArray()` instead.

=== Deploying to '<omitted>'...

i  deploying functions
i  functions: preparing codebase default for deployment
i  functions: ensuring required API cloudfunctions.googleapis.com is enabled...
i  functions: ensuring required API cloudbuild.googleapis.com is enabled...
i  artifactregistry: ensuring required API artifactregistry.googleapis.com is enabled...
✔  artifactregistry: required API artifactregistry.googleapis.com is enabled
✔  functions: required API cloudfunctions.googleapis.com is enabled
✔  functions: required API cloudbuild.googleapis.com is enabled
⚠  functions: package.json indicates an outdated version of firebase-functions. Please upgrade using npm install --save firebase-functions@latest in your functions directory.
i  functions: Loading and analyzing source code for codebase default to determine what to deploy
Serving at port 8460

Error [ERR_REQUIRE_ASYNC_MODULE]: require() cannot be used on an ESM graph with top-level await. Use import() instead. To see where the top-level await comes from, use --experimental-print-required-tla.
    at ModuleJobSync.runSync (node:internal/modules/esm/module_job:392:13)
    at ModuleLoader.importSyncForRequire (node:internal/modules/esm/loader:329:47)
    at loadESMFromCJS (node:internal/modules/cjs/loader:1414:24)
    at Module._compile (node:internal/modules/cjs/loader:1547:5)
    at Object..js (node:internal/modules/cjs/loader:1677:16)
    at Module.load (node:internal/modules/cjs/loader:1318:32)
    at Function._load (node:internal/modules/cjs/loader:1128:12)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:219:24)
    at Module.require (node:internal/modules/cjs/loader:1340:12) {
  code: 'ERR_REQUIRE_ASYNC_MODULE'
}


Error: Functions codebase could not be analyzed successfully. It may have a syntax or runtime error
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
Error: Process completed with exit code 1.

[aalej]

Thanks for the detailed report, @gustavopch! I'm currently working on reproducing this, but so far I haven't encountered the issue when deploying functions. I created this test case using the information provided. Could you let me know I may be missing anything here? Also, which version of firebase-functions are you currently using?

[gustavopch]

@aalej I'm using firebase-functions@6.1.1. Looking at this line, I believe your repro is using Node.js v18, right? If so, then you need to change it to v22.12.0.

[aalej]

Thanks for pointing that out. I'm getting an error when settings engines.node to 22.12.0:

Error: Detected node engine 22.12.0 in package.json, which is not a supported version. Valid versions are 10, 12, 14, 16, 18, 20, 22

So instead I set it to 22. I also tried using firebase-functions@6.1.1, but still, no errors are being raised when deploying.

Any chance you could share additional details about your project's setup? Such as if you're using TypeScript or JavaScript and the functions section of your firebase.json? Sample code snippets of the functions you're deploying would also be helpful.

[gustavopch]

@aalej My engines.node is set to 22.x. Can you confirm your installed version of Node.js is v22.12.0 with node --version? That will be necessary to reproduce the problem. In my project, I've pinned Node.js to v22.11.0 in my GitHub Actions workflow to work around the error and it's working well.

My firebase.json is:

{
  "functions": {
    "runtime": "nodejs22",
    "source": "."
  }
}

Another thing that may be relevant is that my package.json has the functions entry set to ./functions/index.js, and in this file I have something like this:

import { register } from 'tsx/esm/api'
register()
export const { fn } = await import('./exports.js')

I'm using tsx@4.19.2 to run TypeScript in the Cloud Functions as a workaround as they don't natively support TypeScript and I find this easier than having to add a build step. The exports.js actually points to a .ts file, i.e. exports.ts, that re-exports my functions from other TS files.

[aalej]

Thanks @gustavopch for the additional info! I'm now able to reproduce the error. I think the error comes from when firebase-functions tries to load the module containing this code:

import { register } from 'tsx/esm/api'
register()
export const { fn } = await import('./exports.js')

Specifically, with this line

export const { fn } = await import('./exports.js')

When trying to deploy with the line above, the error gets raised. I'll check this with our engineering team so they can take a look. I've also updated the test case.

[taeold]

@gustavopch fwiw, you might want to create an issue in https://github.com/GoogleCloudPlatform/functions-framework-nodejs too.

Functions Framework would probably fail in the exact same way the Firebase CLI is failing here. See https://github.com/GoogleCloudPlatform/functions-framework-nodejs/blob/f607b54c2474bcee56afef03a1e8c612ccf14480/src/loader.ts#L74

[taeold]

@gustavopch fwiw, you might want to create an issue in https://github.com/GoogleCloudPlatform/functions-framework-nodejs too.

Functions Framework would probably fail in the exact same way the Firebase CLI is failing here. See https://github.com/GoogleCloudPlatform/functions-framework-nodejs/blob/f607b54c2474bcee56afef03a1e8c612ccf14480/src/loader.ts#L74

oh nvm - functions framework uses more granular ESM module checks and won't have this issue iiuc.