Help us improve
Share bugs, ideas, or general feedback.
From firebase-development
Troubleshoots Firebase emulator issues, Firestore rules violations, Cloud Functions errors, auth problems, and deployment failures using logs, Emulator UI, and Rules Playground.
npx claudepluginhub 2389-research/claude-plugins --plugin firebase-developmentHow this skill is triggered — by the user, by Claude, or both
Slash command
/firebase-development:debugThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This sub-skill guides systematic troubleshooting of Firebase development issues. It handles emulator problems, rules violations, function errors, auth issues, and deployment failures.
Guides Firebase usage including Auth, Firestore, Realtime DB, Cloud Functions, Storage, and Hosting. Covers security rules, data modeling for query patterns, and denormalization.
Build and configure Firebase-powered web and mobile apps: Firestore, Auth, Hosting, Cloud Functions, Storage, App Check, Remote Config, Analytics. Use for authentication flows, data modeling, hosting deployment, security rules.
Foundational Firebase CLI setup, authentication, and project management. Use for checking CLI version, initializing, authenticating, setting projects, and configuring google-services/GoogleService-Info files.
Share bugs, ideas, or general feedback.
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:
Do not use for:
firebase-development:project-setupfirebase-development:add-featurefirebase-development:validateCreate checklist with these 10 steps:
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.
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
open http://127.0.0.1:4000
Use Emulator UI to:
In Emulator UI → Firestore → Rules Playground:
Reference: docs/examples/firestore-rules-patterns.md
Add strategic console.log statements:
Watch terminal output while reproducing.
Reference: docs/examples/express-function-architecture.md
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
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
Before making fixes:
# Graceful shutdown (Ctrl+C exports automatically)
# Or manual export:
firebase emulators:export ./backup-data
Verify export: ls -la .firebase/emulator-data/
Apply fix based on diagnosis, then:
firebase emulators:start --import=.firebase/emulator-data
Verify:
Create entry in docs/debugging-notes.md:
| 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 |
If Firebase-specific tools don't reveal root cause, invoke superpowers:systematic-debugging for:
docs/examples/emulator-workflow.mddocs/examples/firestore-rules-patterns.mddocs/examples/api-key-authentication.mddocs/examples/express-function-architecture.md