firebase deploy cannot load your functions: user code failed to load
Failed to load function definition from source: FirebaseError: User code failed to load. Cannot determine backend specificationShort 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.
Fix it fast
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')"2Match what you see, then jump to its fix
- 1
Cannot find module '.../lib/index.js' in the output of the command abovepackage.json main points at output that was never builtFix - 2
The 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
The node command runs without error but the deploy still finds no functionsThe entry file does not export the functions where the CLI looksFix - 4
a SyntaxError about import or export, or ERR_REQUIRE_ASYNC_MODULE, in the node outputA file mixes ES module and CommonJS syntaxFix
- 1
What does the error look like?
Failed to load function definition from source: FirebaseError: User code failed to load. Cannot determine backend specificationFunctions 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.js2Fix
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 functionsConfirmed by firebase.google.com
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 functions3Verify
The deploy now gets past the analysis step.
firebase deploy --only functionsConfirmed by firebase.google.com
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
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.json2Fix
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
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:
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Back end
firebase deploy stops because the predeploy lint step failed
Error: There was an error deploying functions
The predeploy hook in firebase.json runs npm run lint before every deploy, and a failing hook cancels the deploy.
3 causes, each with a fixBack end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fixBack end
corepack enable fails: permission denied while creating the pnpm link
Internal Error: EACCES: permission denied, symlink '../lib/node_modules/corepack/dist/pnpm.js' -> '/usr/local/bin/pnpm'
corepack enable writes small link files for yarn and pnpm next to your node binary.
2 causes, each with a fixBack end
Create React App says Node is too old, and npm will not run on the new one
npm does not support Node.js v10.19.0
The shell is running an old Node.js that is below the version Create React App needs.
3 causes, each with a fixBack end
Firebase Cloud Functions respond slowly, especially on the first call
Every function in the project is slow after deploy, even tiny ones
Most slow first calls are cold starts: the runtime starts from scratch, loads your code and runs global-scope work before it can answer.
3 causes, each with a fixBack 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