Firebase Debugging

Overview

This sub-skill guides systematic troubleshooting of Firebase development issues. It handles emulator problems, rules violations, function errors, auth issues, and deployment failures.

Key principles:

Identify issue type first (emulator, rules, functions, auth, deployment)
Use Emulator UI and Rules Playground for diagnosis
Export emulator state before restarting
Document issues and solutions for future reference

When This Sub-Skill Applies

Emulators won't start or have port conflicts
Getting Firestore rules violations (PERMISSION_DENIED)
Cloud Functions returning errors or not executing
Authentication not working in emulators
Deployment fails with cryptic errors
User says: "debug", "troubleshoot", "error", "not working", "failing"

Do not use for:

Setting up new projects → firebase-development:project-setup
Adding new features → firebase-development:add-feature
Code review without specific errors → firebase-development:validate

TodoWrite Workflow

Create checklist with these 10 steps:

Step 1: Identify Issue Type

Categorize the error:

Category	Symptoms	Keywords
Emulator Won't Start	Port conflicts, initialization errors	"EADDRINUSE", "emulator failed"
Rules Violation	Permission denied on read/write	"PERMISSION_DENIED", "insufficient"
Function Error	HTTP 500, timeout, not executing	"function failed", "timeout"
Auth Issue	Token errors, not authenticated	"auth failed", "invalid token"
Deployment Failure	Deploy command fails	"deployment failed", "deploy error"

If unclear, use AskUserQuestion to clarify issue type.

Step 2: Check Emulator Logs and Terminal

For running emulators: Watch terminal output while reproducing the issue.

For emulators that won't start:

lsof -i :4000 && lsof -i :5001 && lsof -i :8080  # Check ports
kill -9 <PID>  # Kill conflicting process

For deployment errors: Check firebase-debug.log

Reference: docs/examples/emulator-workflow.md

Step 3: Open Emulator UI

open http://127.0.0.1:4000

Use Emulator UI to:

View Firestore data and structure
Check authenticated users
Review function invocation logs
Search consolidated logs

Step 4: Test Rules in Playground (If Rules Issue)

In Emulator UI → Firestore → Rules Playground:

Select operation type (get/list/create/update/delete)
Specify document path
Set auth context (uid, custom claims)
Add request data for writes
Run simulation and review evaluation trace

Reference: docs/examples/firestore-rules-patterns.md

Step 5: Add Debug Logging (If Function Error)

Add strategic console.log statements:

Function entry confirmation
Input data (req.body, req.params)
Auth context (userId, API key)
Intermediate operation results
Error details with stack trace

Watch terminal output while reproducing.

Reference: docs/examples/express-function-architecture.md

Step 6: Verify Auth Configuration (If Auth Issue)

Check environment variables:

cat functions/.env
cat hosting/.env.local  # Should have NEXT_PUBLIC_USE_EMULATORS=true

Check emulator connection in client code and API key middleware.

Reference: docs/examples/api-key-authentication.md

Step 7: Check Deployment Config (If Deployment Failure)

cat firebase-debug.log  # Full error details
cat firebase.json       # Config issues
cat .firebaserc         # Project ID
firebase target:list    # Verify targets

Test predeploy hooks locally:

cd functions && npm run build

Step 8: Export Emulator State

Before making fixes:

# Graceful shutdown (Ctrl+C exports automatically)
# Or manual export:
firebase emulators:export ./backup-data

Verify export: ls -la .firebase/emulator-data/

Step 9: Implement and Test Fix

Apply fix based on diagnosis, then:

firebase emulators:start --import=.firebase/emulator-data

Verify:

Original error no longer occurs
Terminal shows success logs
Emulator UI confirms expected behavior

Step 10: Document Issue and Solution

Create entry in docs/debugging-notes.md:

Symptom and exact error message
Root cause
Solution applied
Prevention for future

Common Issues Quick Reference

Issue	Solution
Port conflicts	`lsof -i :<port>`, kill process
Data persistence lost	Use Ctrl+C (not kill) to stop emulators
Cold start delays	First call takes 5-10s (normal)
Rules not reloading	Restart emulators
Admin vs Client SDK	Admin bypasses rules, client respects them
Missing CORS	Add `app.use(cors({ origin: true }))`
Emulator connection	Set `NEXT_PUBLIC_USE_EMULATORS=true`
API key prefix	Verify prefix matches actual keys

Integration with Superpowers

If Firebase-specific tools don't reveal root cause, invoke superpowers:systematic-debugging for:

Complex multi-service interactions
Race conditions or timing issues
Call stack tracing beyond Firebase layer

Pattern References

Emulator workflow: docs/examples/emulator-workflow.md
Rules patterns: docs/examples/firestore-rules-patterns.md
Auth patterns: docs/examples/api-key-authentication.md
Functions: docs/examples/express-function-architecture.md

aiskillstore-firebase-development-debug