Troubleshooting

This guide covers common issues you might encounter while developing OOOC Fête Finder and their solutions.

Environment Issues

Missing DATABASE_URL

Error: DATABASE_URL is required

Symptom:

DATABASE_URL (or POSTGRES_URL) is required to bootstrap Postgres store.

Solution:Add DATABASE_URL to your .env.local:

.env.local

DATABASE_URL=postgresql://user:password@host:port/database

Or use POSTGRES_URL as an alias:

.env.local

POSTGRES_URL=postgresql://user:password@host:port/database

For local development, you can use a local Postgres instance:

DATABASE_URL=postgresql://localhost:5432/oooc_fete_finder

Missing AUTH_SECRET

Error: AUTH_SECRET must be at least 32 characters

Symptom:

Admin login fails
Token generation errors
Rate limiting breaks

Solution:Generate a secure random string (32+ characters):

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Add to .env.local:

.env.local

AUTH_SECRET=your-generated-secret-here-must-be-at-least-32-characters-long

Never commit AUTH_SECRET to version control. Use different secrets for development and production.

DATA_MODE not set

Error: DATA_MODE is required in production

Symptom:

App fails fast at startup: DATA_MODE is required in production

Solution:Set DATA_MODE in your environment:

.env.local

DATA_MODE=remote

Valid values:

remote: Use Postgres event store with CSV fallback (production)
local: Development mode (not recommended for production)

The app enforces DATA_MODE=remote in production deployments to prevent misconfiguration.

Database Issues

Connection timeout

Error: Connection timeout / ECONNREFUSED

Symptom:

connect ECONNREFUSED 127.0.0.1:5432

Causes:

Postgres is not running
Wrong host/port in DATABASE_URL
Network firewall blocking connection
Postgres not accepting remote connections

Solutions:1. Check if Postgres is running:

ps aux | grep postgres

2. Verify connection string format:

postgresql://username:password@host:port/database

3. Test connection directly:

psql "$DATABASE_URL"

4. For Vercel Postgres: Ensure you’re using the pooled connection string from the Vercel dashboard.

Table does not exist

Error: relation app_kv_store does not exist

Symptom:

error: relation "app_kv_store" does not exist

Solution:Run the bootstrap script to create tables:

pnpm bootstrap:postgres-store

This creates:

app_kv_store
app_event_store_columns
app_event_store_rows
app_event_store_meta
app_event_store_settings

Verify tables exist:

pnpm db:cli -- status

Row count mismatch

Warning: Row counts don't match

Symptom: From pnpm db:cli -- rows:

- table rows count: 81
- table meta row_count: 75
- table counts match: no

Causes:

Partial import failure
Manual database modifications
Interrupted save operation

Solution:1. Check for data corruption:

pnpm db:cli -- sample 10

2. Re-import from backup: Use admin panel → Operations → Restore from backup3. Force fresh import:

pnpm bootstrap:postgres-store

Bootstrapping will skip seeding if tables already contain data. To force re-seed, manually clear tables first (use with caution).

Build Issues

Module not found

Error: Module not found: Can't resolve '@/...'

Symptom:

Module not found: Can't resolve '@/features/...'

Solutions:1. Clear Next.js cache:

rm -rf .next
pnpm dev

2. Clear node_modules and reinstall:

rm -rf node_modules pnpm-lock.yaml
pnpm install

3. Verify tsconfig.json paths:

tsconfig.json

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Type errors

Build fails with TypeScript errors

Symptom:

Type error: Property 'xyz' does not exist on type '...'

Solutions:1. Run type checker:

pnpm exec tsc --noEmit

2. Common fixes:

Update type definitions: pnpm add -D @types/node @types/react
Restart TypeScript server in VS Code: Cmd+Shift+P → “TypeScript: Restart TS Server”
Check for version mismatches between react and @types/react

3. Skip type checking temporarily:

pnpm build --no-lint

Only skip type checking for debugging. Always fix type errors before committing.

Out of memory

Error: JavaScript heap out of memory

Symptom:

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Solution:Increase Node.js heap size:

NODE_OPTIONS="--max-old-space-size=4096" pnpm build

Or add to .env:

NODE_OPTIONS=--max-old-space-size=4096

Testing Issues

Tests fail with environment errors

Error: Environment variable not defined

Symptom:

ReferenceError: process.env.AUTH_SECRET is not defined

Solution:Ensure test/setup-env.ts is configured in vitest.config.ts:

vitest.config.ts

export default defineConfig({
  test: {
    setupFiles: ["test/setup-env.ts"],
  },
});

Verify setup file exists:

test/setup-env.ts

process.env.AUTH_SECRET ??= "test-auth-secret-0123456789...";
process.env.DATA_MODE ??= "remote";

Mock not working

Error: Mocked module returns real implementation

Symptom: Mocked functions call real implementations instead of mocks.Solutions:1. Reset modules before mocking:

vi.resetModules();
vi.doMock("@/lib/module", () => ({ ... }));
const module = await import("@/lib/module");

2. Use dynamic imports:

// Don't do this
import { fn } from "@/lib/module";
vi.mock("@/lib/module"); // Too late!

// Do this
vi.doMock("@/lib/module", () => ({ fn: vi.fn() }));
const { fn } = await import("@/lib/module");

3. Clear mocks between tests:

beforeEach(() => {
  vi.clearAllMocks();
});

Coverage not generated

Error: Coverage directory is empty

Symptom: Running pnpm test:coverage doesn’t generate HTML reports.Solutions:1. Verify coverage config:

vitest.config.ts

coverage: {
  provider: "v8",
  reporter: ["text", "html"],
  include: [
    "features/data-management/**/*.ts",
    "lib/platform/postgres/**/*.ts",
    "features/auth/**/*.ts",
  ],
}

2. Install coverage provider:

pnpm add -D @vitest/coverage-v8

3. Check reporter output: Look for coverage/index.html in project root.

Runtime Issues

Admin login returns 401 Unauthorized

Symptoms:

Admin panel login fails
x-admin-key header rejected
/api/admin/* endpoints return 401

Solutions:1. Verify ADMIN_KEY is set:

echo $ADMIN_KEY

2. Check key matches: Ensure the key in .env.local matches what you’re using in the UI.3. Restart dev server:

pnpm dev

4. Clear browser cache: Admin session tokens may be stale.

If ADMIN_KEY is not set, all admin endpoints are disabled. This is intentional for builds without admin access.

Rate limit errors

Error: 429 Too Many Requests

Symptom:

HTTP 429: Rate limit exceeded
Retry-After: 42

Causes:

POST /api/auth/verify: 60/min per IP, 6/15min per email+IP
POST /api/event-submissions: 20/10min per IP, 5/60min per email+IP
POST /api/track: Rate limited per IP

Solutions:1. Wait for reset: Check Retry-After header for seconds until reset.2. Clean up test counters:

curl -X GET "http://localhost:3000/api/cron/cleanup-rate-limits" \
  -H "Authorization: Bearer $CRON_SECRET"

3. Check repository health:

pnpm health:check

4. In development, clear Postgres:

DELETE FROM app_kv_store WHERE key LIKE 'rate_limit:%';

Do not clear rate limits in production. This defeats abuse protection.

Featured events not showing

Featured events don't appear on homepage

Symptom: Events marked as featured in CSV or admin don’t show up.Causes:

Legacy Featured column used (now deprecated)
Schedule entries not created
Effective times are in the past

Solutions:1. Migrate to scheduler:

pnpm bootstrap:featured-schedule

2. Use Featured Events Manager: Go to /admin → Featured Events Manager → “Feature now”3. Verify schedule: Check app_featured_event_schedule table for active entries with:

status = 'scheduled'
effective_start_at <= NOW()
effective_end_at >= NOW()

4. Revalidate cache: From admin panel → Operations → “Revalidate Homepage”

CSV import fails

Error: CSV structure mismatch

Symptom:

Import fails with row count errors
Events missing after import
Columns misaligned

Solutions:1. Diagnose CSV structure:

pnpm csv:diagnose -- --remote

2. Common issues:

Unquoted commas: Wrap cells with commas in double quotes
Line breaks in cells: Use quoted strings: "Line 1\nLine 2"
Stray quotes: Escape with double quotes: "She said ""hello"""

3. Fix in Google Sheets:

Check for extra columns at the end
Remove trailing commas
Verify header row is row 1

4. Test with local file:

pnpm csv:diagnose -- --file data/events.csv

Geocoding not working

Map shows default location instead of event location

Symptom: Events appear at default coordinates instead of actual addresses.Causes:

GOOGLE_MAPS_API_KEY not set
Geocoding API not enabled in Google Cloud Console
Coordinate cache not warmed

Solutions:1. Enable Geocoding API: Google Cloud Console → APIs & Services → Enable “Geocoding API”2. Set API key:

.env.local

GOOGLE_MAPS_API_KEY=your-api-key-here

3. Warm coordinate cache: From admin panel → Operations → “Save & Revalidate”This pre-geocodes all event locations and stores in maps:locations:v1 KV key.4. Check cache status:

pnpm db:cli -- get maps:locations:v1

Without geocoding, events fall back to estimated coordinates based on district/area.

Development Workflow Issues

Hot reload not working

Changes not reflected in browser

Symptom: Code changes don’t trigger browser refresh.Solutions:1. Restart dev server:

pnpm dev

2. Clear Next.js cache:

rm -rf .next
pnpm dev

3. Check Turbopack: Ensure dev script uses --turbopack flag:

package.json

{
  "scripts": {
    "dev": "next dev --turbopack"
  }
}

4. Disable browser cache: Open DevTools → Network → Disable cache

Biome formatting conflicts

Files keep getting reformatted

Symptom: Biome and other formatters fight over formatting.Solutions:1. Use Biome exclusively: Disable Prettier, ESLint auto-format in editor.2. Run format before commit:

pnpm fix

3. Configure VS Code:

.vscode/settings.json

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true
}

Deployment Issues

Build succeeds locally but fails in Vercel

Error: Build fails in Vercel but works locally

Common causes:

Environment variables not set in Vercel
Node version mismatch
Build cache issues

Solutions:1. Set environment variables: Vercel Dashboard → Project → Settings → Environment VariablesRequired:

AUTH_SECRET
DATABASE_URL
DATA_MODE=remote

2. Match Node versions: Check .node-version or package.json engines field.3. Clear build cache: Vercel Dashboard → Deployments → ⋮ → Redeploy → Clear cache

Post-deploy stale data

New deployment shows old events

Symptom: After deploying, site shows cached/stale event data.Solution:Trigger post-deploy revalidation:

curl -X POST "https://your-domain.com/api/revalidate/deploy" \
  -H "Authorization: Bearer $DEPLOY_REVALIDATE_SECRET"

This forces:

Live events reload from Postgres
Homepage revalidation
Fresh ISR cache

Set up in CI/CD: Add as a post-deployment step in Vercel or GitHub Actions.

Getting Help

If you encounter an issue not covered here:

Check logs:
- Development: Console output from pnpm dev
- Production: Vercel deployment logs
- Database: pnpm health:check

Run diagnostics:

pnpm health:check
pnpm db:cli -- status
pnpm csv:diagnose -- --remote

Review documentation:
Check source code: Many scripts have detailed inline comments explaining behavior.
Report issues: If you find a bug, document the error message, steps to reproduce, and environment details.

Configuration

Development

Environment Issues

Missing DATABASE_URL

Missing AUTH_SECRET

DATA_MODE not set

Database Issues

Connection timeout

Table does not exist

Row count mismatch

Build Issues

Module not found

Type errors

Out of memory

Testing Issues

Tests fail with environment errors

Mock not working

Coverage not generated

Runtime Issues

Rate limit errors

Featured events not showing

CSV import fails

Geocoding not working

Development Workflow Issues

Hot reload not working

Biome formatting conflicts

Deployment Issues

Build succeeds locally but fails in Vercel

Post-deploy stale data

Getting Help

Build docs developers (and LLMs) love

Configuration

Development

Documentation Index

​Environment Issues

​Missing DATABASE_URL

​Missing AUTH_SECRET

​DATA_MODE not set

​Database Issues

​Connection timeout

​Table does not exist

​Row count mismatch

​Build Issues

​Module not found

​Type errors

​Out of memory

​Testing Issues

​Tests fail with environment errors

​Mock not working

​Coverage not generated

​Runtime Issues

​Admin login fails

​Rate limit errors

​Featured events not showing

​CSV import fails

​Geocoding not working

​Development Workflow Issues

​Hot reload not working

​Biome formatting conflicts

​Deployment Issues

​Build succeeds locally but fails in Vercel

​Post-deploy stale data

​Getting Help

Build docs developers (and LLMs) love

Environment Issues

Missing DATABASE_URL

Missing AUTH_SECRET

DATA_MODE not set

Database Issues

Connection timeout

Table does not exist

Row count mismatch

Build Issues

Module not found

Type errors

Out of memory

Testing Issues

Tests fail with environment errors

Mock not working

Coverage not generated

Runtime Issues

Admin login fails

Rate limit errors

Featured events not showing

CSV import fails

Geocoding not working

Development Workflow Issues

Hot reload not working

Biome formatting conflicts

Deployment Issues

Build succeeds locally but fails in Vercel

Post-deploy stale data

Getting Help