firebase-development-debug

name	firebase-development:debug
description	This skill should be used when troubleshooting Firebase emulator issues, rules violations, function errors, auth problems, or deployment failures. Triggers on "error", "not working", "debug", "troubleshoot", "failing", "broken", "permission denied", "emulator issue".

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:

1. Select operation type (get/list/create/update/delete)
2. Specify document path
3. Set auth context (uid, custom claims)
4. Add request data for writes
5. 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