Troubleshooting Guide

Common issues and their solutions. Can't find your issue? Join our Discord for help.

Quick Fixes

# Most issues can be resolved with these commands:

docker login              # Fix rate limit errors
npm run docker:health     # Check if services are running
npm run docker:reset      # Reset database and re-run migrations
npm run docker:seed       # Reset + create test users

Docker Issues

"Rate exceeded" error during Docker pull

Docker Hub limits anonymous users to 100 pulls per 6 hours.

# Solution: Authenticate with Docker Hub
docker login

# Enter your Docker Hub username and password
# (Create free account at https://hub.docker.com/signup)

# Then restart setup:
npx supabase stop
./scripts/first-time-setup.sh

Docker not running

Supabase requires Docker Desktop to be running.

# Check Docker status
docker info

# If not running, start Docker Desktop
# Then run:
npm run docker:start

"stdout is not a tty" on Windows

Running bash script from PowerShell or CMD without proper terminal.

# Solution: Use the batch file instead
scripts\first-time-setup.bat

# Or open Git Bash and run:
./scripts/first-time-setup.sh

Database Issues

Database connection failed

Supabase services may not be running or ports may be blocked.

# Reset everything
npm run docker:stop
npm run docker:start
npm run docker:health

# Check status
supabase status

Migrations not applied / Missing tables

Database schema wasn't set up correctly.

# Reset database and re-run migrations
npm run docker:reset

# Create test users
npx tsx scripts/create-seed-users.ts

Row Level Security (RLS) errors

"new row violates row-level security policy" or similar.

# Check your user's permissions
npx tsx scripts/debug-permissions.ts user@example.com

# Verify RLS policies in Supabase Studio
npm run docker:studio
# Open http://localhost:54323
# Navigate to Database → Policies

RLS errors usually mean the user doesn't have permission. Check their role assignments.

Authentication Issues

Can't login with test accounts

Test users may not be created yet.

# Create test users
npm run docker:seed

# Or manually:
npx tsx scripts/create-seed-users.ts

# Test accounts (password: Test1234!)
# superadmin@test.local
# exec@test.local
# manager@test.local
# pm@test.local

JWT or token errors

Environment variables may be misconfigured or mismatched.

# Check your .env.local matches your environment

# For LOCAL Docker:
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=eyJhbGci...

# For CLOUD Supabase:
NEXT_PUBLIC_SUPABASE_URL=https://your-ref.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=your-cloud-key

# Keys MUST match the URL environment!

Permission Issues

User can't access feature / Permission denied

User may be missing required role or permission.

# Debug user permissions
npx tsx scripts/debug-permissions.ts user@example.com

# Check user's roles in database
SELECT up.email, r.name as role_name
FROM user_profiles up
JOIN user_roles ur ON up.id = ur.user_id
JOIN roles r ON ur.role_id = r.id
WHERE up.email = 'user@example.com';

# Check role's permissions
SELECT r.name, rp.permission, rp.granted
FROM roles r
LEFT JOIN role_permissions rp ON r.id = rp.role_id
WHERE r.name = 'Role Name';

UI shows button but action fails

Permission check may be missing on the server action.

Solution: Ensure the API route or server action includes a permission check:

// In server action
const canEdit = await hasPermission(
  userProfile,
  Permission.EDIT_ACCOUNT
);
if (!canEdit) {
  return { error: 'Permission denied' };
}

Build Issues

TypeScript errors on build

Type checking fails during npm run build.

# Check for type errors
npx tsc --noEmit

# Common fixes:
# 1. Update types: npm run generate-types
# 2. Check for missing dependencies
# 3. Ensure .env.local exists

Still Need Help?

Can't find your issue? Join our Discord community or open a GitHub issue.

Join Discord Open Issue