How to Debug Firebase Functions Locally with the Emulator Suite

If you have not set up emulators yet, run firebase init emulators in your project directory. Select the Functions emulator (and optionally Firestore, Auth, and Storage if your functions interact with those services). The CLI will download the required emulator binaries. Accept the default ports or customize them. The functions emulator defaults to port 5001.

1# In your Firebase project root
2firebase init emulators
3
4# Select: Functions Emulator, Firestore Emulator (optional)
5# Accept default ports or customize
6# Download emulators when prompted

Run firebase emulators:start from your project root. The CLI compiles your functions and starts each emulator on its configured port. The Emulator UI launches at localhost:4000, giving you a dashboard to browse Firestore data, manage Auth users, and view function logs. If your functions use environment variables, create a .env file in your functions directory — the emulator reads it automatically.

1# Start all configured emulators
2firebase emulators:start
3
4# To persist data between sessions:
5firebase emulators:start --export-on-exit=./emulator-data --import=./emulator-data

In your frontend code, use connectFunctionsEmulator to redirect all function calls to localhost instead of production. This should only run in development mode. The emulator handles both onCall and onRequest functions identically to production, including authentication context when the Auth emulator is also running.

1import { initializeApp } from 'firebase/app';
2import { getFunctions, connectFunctionsEmulator } from 'firebase/functions';
3
4const app = initializeApp(firebaseConfig);
5const functions = getFunctions(app);
6
7// Connect to local emulator in development
8if (process.env.NODE_ENV === 'development') {
9  connectFunctionsEmulator(functions, '127.0.0.1', 5001);
10}

Create a simple callable function to verify the emulator is working. Export it from your functions/index.ts file. After saving, the emulator hot-reloads automatically. Call the function from your app or use curl for an onRequest function. Watch the Emulator UI Logs tab for the invocation details.

1// functions/src/index.ts
2import { onCall, HttpsError } from 'firebase-functions/v2/https';
3import { logger } from 'firebase-functions/v2';
4
5export const greet = onCall((request) => {
6  logger.info('greet called', { uid: request.auth?.uid });
7
8  if (!request.auth) {
9    throw new HttpsError('unauthenticated', 'Must be signed in');
10  }
11
12  const name = request.data.name || 'World';
13  logger.info('Greeting', { name });
14  return { message: `Hello, ${name}!` };
15});

To set breakpoints and step through function code, start the emulator with the --inspect-functions flag. This opens a Node.js debugging port (default 9229). Then create a VS Code launch configuration that attaches to that port. Set breakpoints in your function code, trigger the function, and VS Code will pause execution at each breakpoint.

1// Start emulator with inspect flag
2// firebase emulators:start --inspect-functions
3
4// .vscode/launch.json
5{
6  "version": "0.2.0",
7  "configurations": [
8    {
9      "type": "node",
10      "request": "attach",
11      "name": "Attach to Functions Emulator",
12      "port": 9229,
13      "restart": true,
14      "skipFiles": ["<node_internals>/**"]
15    }
16  ]
17}

Open localhost:4000 in your browser and navigate to the Logs tab. All logger.info, logger.warn, and logger.error calls from your functions appear here in real time. You can filter by severity level and search for specific text. Structured log data (objects passed as second argument to logger methods) is displayed as expandable JSON, making it easy to inspect request payloads and error details.

1// Use structured logging for better debugging
2import { logger } from 'firebase-functions/v2';
3
4// Instead of:
5logger.info('User created: ' + uid);
6
7// Use structured data:
8logger.info('User created', {
9  uid,
10  email: request.data.email,
11  timestamp: new Date().toISOString()
12});