Troubleshooting

Quick fixes for the most common issues you’ll encounter during setup, development, and deployment.

Quick Reference

Issue	Fix
Git hooks not running	Run npm install to reinstall Husky hooks
AI ignoring project patterns	Be explicit: “Follow AGENTS.md” in your prompts
Port conflicts	See Port Conflicts below
Tests failing	Restart services and re-run tests
Prisma errors after changes	Regenerate client and run migrations
Build fails in CI/CD	Test locally first with npm run build
Peer dependency conflicts	Install with --legacy-peer-deps flag
Cache/build issues	Clear cache and rebuild

AI Framework Issues

Git Hooks Not Working

Problem: Commits succeed but no documentation is generated.

Fix: Run npm install to reinstall Husky hooks. Hooks are managed by Husky and auto-install via npm.

For more on how auto-documentation works, see Keeping Docs Synced.

AI Ignoring Project Patterns

Problem: AI generates generic code and doesn’t follow your project conventions.

Fix: Be explicit in your prompts — plan mode alone doesn’t guarantee the AI will follow patterns:

• “Follow AGENTS.md”
• “Check that scoped rules loaded for testing and security”
• “Use patterns from existing code in the dashboard”

For effective prompt patterns, see Prompt Library & Skills.

Setup Issues

General rule: If something goes wrong during setup, clean up before retrying:

make setup-cleanup  # Remove all resources
make setup          # Start fresh

Authentication Issues

Symptoms: “Not authenticated” or “credentials expired” errors.

Re-authenticate with the relevant services and retry setup. Both Google Cloud and GitHub CLI credentials may need refreshing.

Missing Prerequisites

Symptoms: “command not found” errors for gcloud, gh, or docker.

Ensure all prerequisites are installed:

Tool	Version	Purpose
Node.js	18+	Runtime
Docker	Latest	Local database
GitHub CLI	Latest	Repository management
gcloud CLI	Latest	GCP deployment (optional)

Port Conflicts

Symptoms: “Port 5432 already in use” or “Port 3000 already in use.”

Check what’s using the port and stop conflicting services. The setup wizard can handle this automatically in most cases.

Development Issues

Common Runtime Errors

Error	Fix
”Cannot find module”	Run npm install
”Prisma Client not found”	Run npx prisma generate
”Database not found”	Start dev server (includes database)
“Clerk keys missing”	Check environment file has all Clerk variables
TypeScript errors	Run npx tsc --noEmit to see all errors
Stale build	Clear cache and rebuild

Docker Issues

If Docker containers are stale or not running, clean them up and restart the dev server. Make sure Docker Desktop is running before starting development.

Prisma Errors

After schema changes, regenerate the Prisma client and run pending migrations. If the database is in an inconsistent state, a reset may be needed (this deletes data).

Tests Timing Out

E2E tests can take over a minute. Tell your AI tool to run tests in background mode to avoid timeout issues.

Deployment Issues

Build Fails in GitHub Actions

Test the build locally first before pushing. Fix any errors, then push again.

Cloud Run Deployment Fails

Common causes:

1. Missing secrets — verify all required secrets are configured
2. IAM permissions — ensure the service account has the correct roles
3. Container crashes — check Cloud Run logs for runtime errors

Production Feature Issues

Issue	Fix
Emails not sending	Register your app with Inngest Cloud
Team invitations fail	Redeploy to auto-configure the app URL
Stripe redirects to wrong URL	Redeploy to auto-configure the app URL
Background jobs not running	Register app URL in Inngest Cloud

For Inngest setup, see Background Jobs. For Stripe configuration, see Billing.

Getting Help

Collect Diagnostics

Run version checks for Node.js, npm, Docker, and your CLI tools. Share the output with your AI assistant for targeted help:

"I'm having [issue]. Here are my diagnostics: [paste version output]"

Additional Resources

• Setup Guide — Installation and configuration
• Prompt Library — Effective AI prompts
• Build Your First Feature — Framework walkthrough