Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

firebase deploy cannot load your functions: user code failed to load

ErrorFailed to load function definition from source: FirebaseError: User code failed to load. Cannot determine backend specification

Short answer

The Firebase CLI loads your functions code on your machine before it deploys, to learn which functions exist. If that load throws, points at a missing file or takes too long, you get this error. Run the entry file with node to see the real exception, then check the main field, the build output and any slow code at the top of the file.

  • Applies to firebase-tools 14, Node.js 22, firebase-functions 6, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Load the entry file the way the CLI does, in the functions folder. Whatever Node.js prints here (a syntax error, a missing module, a failed require) is the real error behind the generic CLI message.

    cd functions
    node -e "require('./index.js')"
  2. 2Match what you see, then jump to its fix

    1. 1Cannot find module '.../lib/index.js' in the output of the command abovepackage.json main points at output that was never builtFix
    2. 2The node command above hangs, or the deploy fails only on a slow machine or CI runnerCode at the top of the file is slow or makes network callsFix
    3. 3The node command runs without error but the deploy still finds no functionsThe entry file does not export the functions where the CLI looksFix
    4. 4a SyntaxError about import or export, or ERR_REQUIRE_ASYNC_MODULE, in the node outputA file mixes ES module and CommonJS syntaxFix

What does the error look like?

  • Failed to load function definition from source: FirebaseError: User code failed to load. Cannot determine backend specification
  • Functions codebase could not be analyzed successfully. It may have a syntax or runtime error

Cause 1 of 4

package.json main points at output that was never built

1Check

TypeScript projects run the compiled file named in main, not the .ts source. If the build step did not run, lib/index.js is missing or stale.

grep '"main"' package.json
ls lib/index.js

2Fix

Build before deploying, and keep a predeploy hook in firebase.json so the build always runs first.

// firebase.json
"functions": [{
  "source": "functions",
  "codebase": "default",
  "predeploy": ["npm --prefix \"$RESOURCE_DIR\" run build"]
}]

3Verify

Deploy again; the CLI now finds the compiled file.

firebase deploy --only functions

Confirmed by firebase.google.com

Did this fix it?

Cause 2 of 4

Code at the top of the file is slow or makes network calls

1Check

The CLI has a time limit for discovering functions. Module-level work such as opening connections, calling an API or loading large files can use it up.

time node -e "require('./index.js')"

2Fix

Move that initialization into the onInit hook of the Firebase Functions SDK, which runs after deploy and not during discovery. As a stop-gap, raise the discovery timeout for one deploy.

export FUNCTIONS_DISCOVERY_TIMEOUT=30
firebase deploy --only functions

3Verify

The deploy now gets past the analysis step.

firebase deploy --only functions

Confirmed by firebase.google.com

Did this fix it?

Cause 3 of 4

The entry file does not export the functions where the CLI looks

1Check

For Node.js the CLI reads exports from index.js (or the file in main). A function defined in another file only counts if index.js re-exports it.

node -e "console.log(Object.keys(require('./index.js')))"

2Fix

Re-export each function from the entry file, either one by one or as a group object.

// index.js
const foo = require('./foo');
exports.foo = foo.foo;
exports.metrics = require('./metrics');

3Verify

The key list now shows every function you expect.

node -e "console.log(Object.keys(require('./index.js')))"

Confirmed by firebase.google.com

Did this fix it?

Cause 4 of 4

A file mixes ES module and CommonJS syntax

1Check

The type field in the nearest package.json decides how .js files are read. Without it they are CommonJS, and import or top-level await then fails.

grep '"type"' package.json

2Fix

Pick one style. Either set the type to module and use import/export everywhere, or keep CommonJS and use require. A .cjs or .mjs extension overrides the type field per file.

// package.json
{ "type": "module" }

3Verify

Run the load check again.

node -e "import('./index.js').then(m => console.log(Object.keys(m)))"

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Run the node load check in CI before firebase deploy so a load error never reaches the deploy step.
  • Keep module-level code to imports and function exports; put clients and connections in onInit or inside the handler.
  • Keep a predeploy build hook for TypeScript projects.
  • Pin one module system per functions folder.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

firebase-admin warns that FIREBASE_CONFIG is missing

Warning, FIREBASE_CONFIG environment variable is missing. Initializing firebase-admin will fail

Cloud Functions for Firebase sets FIREBASE_CONFIG for you; a script run with plain node does not have it.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.