Firebase Cloud Functions Crashing on Default Node Runtime

What Happened

During TrustSeal's initial build (early February 2026), Firebase Cloud Functions were deployed for the Gemini AI analysis and Razorpay webhook handling. The firebase deploy --only functions command succeeded with no errors. Firebase Console showed the functions as "Active."

But every invocation failed. The Gemini analysis Cloud Function returned 500 errors to the client. The Firebase Console logs showed the function had started (cold start completed) but then immediately threw:

Unhandled Promise Rejection: Cannot find module '...'

or in some invocations:

Error: package exports do not define a valid 'exports' main

The local Firebase emulator (firebase emulators:start) ran without any errors using the same code. This masked the issue during development — the emulator used the local Node.js version (22 at time of development), while the deployed functions used Firebase's default runtime.

The Runtime Version Gap

Firebase Functions v2 (Cloud Run-based) defaults to Node 18 unless explicitly specified. At the time of this incident, the firebase-admin SDK version in use, combined with specific npm packages for the Gemini integration, had known issues on Node 18 related to ESM exports and module resolution changes that were resolved in Node 20/22.

The emulator used the local Node version — which was 22. Production used Node 18. The codebase worked on one and crashed on the other.

The rule: Never assume the Firebase emulator runtime matches the deployed runtime. The emulator uses your local Node binary. Firebase production uses the runtime declared in firebase.json (defaulting to Node 18 if not set).

firebase.json Configuration

Before (implicit default — Node 18):

{
  "functions": {
    "source": "functions"
  }
}

After (explicit Node 22):

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

Also update functions/package.json:

{
  "engines": {
    "node": "22"
  }
}

The engines field tells npm which Node version to expect. Without it, Firebase Functions CLI may warn or select a different runtime than intended.

Why This Happens

Firebase Functions v2 uses Google Cloud Run. Cloud Run images are pinned to a specific Node runtime that doesn't change unless you explicitly update it. The Firebase default is chosen for stability and broad compatibility — not for compatibility with the latest npm ecosystem.

As npm packages adopt newer Node features (ESM, exports field in package.json, top-level await), they may require a more recent Node runtime than Firebase's default. The incompatibility only surfaces at execution time in the deployed environment.

Resolution

Updating firebase.json to set "runtime": "nodejs22" and running firebase deploy --only functions was the complete fix. The functions deployed to Node 22 runtime, all module resolution errors disappeared, and the Gemini analysis and Razorpay webhook functions executed correctly.

No code changes were required — the issue was purely the runtime version mismatch.

Operational Impact

• TrustSeal Gemini AI analysis was non-functional in production for the duration of the debugging session
• Razorpay webhook processing was also failing (same runtime environment, same crash pattern)
• Both products appeared fully deployed but were silently broken for all Cloud Function-dependent features

Prevention

Firebase Functions deployment checklist:

• firebase.json explicitly declares "runtime": "nodejs22" (or current stable)
• functions/package.json has matching "engines": { "node": "22" } field
• After deploying, immediately invoke one function from the production app and verify in Firebase Console → Functions → Logs that execution completed without errors
• Never treat firebase deploy success as production validation — the deploy succeeds even if the function will crash on invocation

Pattern: This is a runtime-environment-scope-drift failure — the development environment (local emulator on Node 22) differs from the production environment (Cloud Run on Node 18 by default) in a way that masks a real incompatibility until production deployment.