Troubleshooting

This guide covers common issues you might encounter when setting up or running Respondeo.

Installation Issues

"Bun not found"

Problem: The bun command is not recognized.

Solution:

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Or via npm
npm install -g bun

Verify installation:

bun --version

"Dependencies failed to install"

Problem: bun install fails with errors.

Solutions:

Clear cache and retry:

rm -rf node_modules bun.lockb
bun install

Update Bun:
```
bun upgrade
```
Check Node compatibility: Ensure you're using a compatible Node.js version (16+) if Bun falls back to Node.

Database Issues

"Database connection failed"

Problem: App can't connect to PostgreSQL.

Solutions:

Check PostgreSQL is running:

# If using Docker
docker compose ps

# Local installation
pg_isready

Verify DATABASE_URL:

# Correct format
DATABASE_URL=postgresql://user:password@localhost:5432/quiz_app

# Not this:
DATABASE_URL=postgres://...  # Wrong protocol
DATABASE_URL=postgresql://localhost:5432/quiz_app  # Missing credentials

Test connection:
```
psql $DATABASE_URL
```

"Database does not exist"

Problem: PostgreSQL database hasn't been created.

Solution:

createdb quiz_app

# Or in psql:
psql -c "CREATE DATABASE quiz_app;"

"Migration failed"

Problem: Database migrations fail to run.

Solutions:

Check database is empty for first migration:

# Reset database (WARNING: deletes all data)
dropdb quiz_app
createdb quiz_app
bun run db:migrate

Use db:push for development:
```
bun run db:push
```
Check migration files: Ensure drizzle/pg/ contains valid SQL files.

Authentication Issues

"OIDC authentication failed"

Problem: Sign-in redirects to error page.

Solutions:

Verify OIDC issuer is accessible:

curl https://your-oidc-provider.com/.well-known/openid-configuration

Check callback URL configuration:

In your OIDC provider, ensure the callback URL is configured:
```
http://localhost:3000/api/auth/callback/hogwarts
```

Verify credentials:

OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_ISSUER=https://your-provider.com

Check groups claim:

If RBAC isn't working, ensure your provider sends a groups claim in the ID token.

"Session not persisting"

Problem: User gets logged out on refresh.

Solutions:

Check BETTER_AUTH_SECRET is set:

# Generate a secure secret
openssl rand -base64 32

Add to .env.local:

BETTER_AUTH_SECRET=your-generated-secret-here

Verify BETTER_AUTH_URL matches app URL:

BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000

Check browser cookies:

Open DevTools → Application → Cookies. Look for better-auth.session_token.

"User has wrong role"

Problem: User doesn't have expected permissions.

Solutions:

Check OIDC groups claim:

Use a JWT debugger (jwt.io) to inspect the ID token. Look for the groups claim.

Verify role mapping:

RBAC_ROLE_ADMIN_GROUPS=admin,staff
RBAC_ROLE_CREATOR_GROUPS=teachers

Check default role:
```
RBAC_DEFAULT_ROLE=user
```

Debug role resolution:

Add logging in your code:

import { getUserRole, resolveRole } from "@/lib/rbac";

const { role, source, matchedGroup } = resolveRole(session.user);
console.log({ role, source, matchedGroup });

See RBAC Guide for details.

Development Issues

"Port 3000 already in use"

Problem: Another process is using port 3000.

Solutions:

Find and kill the process:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Use a different port:
```
PORT=3001 bun run dev
```

"Changes not reflecting"

Problem: Code changes don't show in the browser.

Solutions:

Hard refresh: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
Clear Next.js cache:
```
rm -rf .next
bun run dev
```
Restart dev server: Stop (Ctrl+C) and restart
Check you're editing the right file:

Remember the monorepo structure:
- App code: apps/web/
- Docs: apps/docs/

"TypeScript errors"

Problem: TypeScript shows errors but code works.

Solutions:

Restart TypeScript server:

In VS Code: Cmd+Shift+P → "Restart TypeScript Server"
Check for multiple TypeScript versions:
```
bun pm ls typescript
```
Regenerate types:
```
bun run tsc --noEmit
```

API Issues

"Invalid API key"

Problem: API requests return 401 Unauthorized.

Solutions:

Check header name:

# Correct
curl -H "x-api-key: your_key" ...

# Incorrect
curl -H "Authorization: Bearer your_key" ...

Verify key hasn't been deleted:

Check /settings in the web UI.

Check for whitespace:

# Trim whitespace
export API_KEY="$(echo $API_KEY | xargs)"

"Rate limit exceeded"

Problem: Getting 429 responses.

Solutions:

Check rate limit headers:
```
curl -I -H "x-api-key: your_key" https://respondeo.example.com/api/quizzes
```
Look for:
- X-RateLimit-Limit
- X-RateLimit-Remaining
- X-RateLimit-Reset
Wait for reset:

The X-RateLimit-Reset header contains the Unix timestamp when limits reset.

Implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status !== 429) return response;

    const delay = Math.min(1000 * Math.pow(2, i), 10000);
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
  throw new Error("Max retries exceeded");
}

Caching Issues

"Stale data in cache"

Problem: Seeing old data even after updates.

Solutions:

Flush Redis/Valkey:

docker compose exec valkey redis-cli FLUSHDB

Lower TTL values:

Edit cache TTL in apps/web/lib/cache/config.ts.
Disable caching temporarily:
```
# Remove or comment out
# REDIS_URL=...
```

"Cache connection error"

Problem: Cache errors in logs.

Solutions:

Check Redis/Valkey is running:
```
docker compose ps valkey
```

Test connection:

docker compose exec valkey redis-cli ping
# Should return: PONG

Verify REDIS_URL:

REDIS_URL=redis://:strongvalkeypassword@localhost:6379

AI Generation Issues

"AI features not configured"

Problem: AI quiz generation button is disabled.

Solutions:

Set API key:

AI_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here

Restart server:
```
# Stop dev server (Ctrl+C)
bun run dev
```
Verify API key is valid:

Test at OpenAI Platform

"AI rate limit exceeded"

Problem: Hit AI generation rate limits.

Solutions:

Wait for reset:

Check RATE_LIMIT_AI_USER_WINDOW_MS (default 24h).

Increase limits (dev only):

RATE_LIMIT_AI_USER=10
RATE_LIMIT_AI_GLOBAL=50

Check provider limits:

OpenAI/Anthropic/Google may have their own rate limits.

Image Search Issues

"Image picker disabled"

Problem: Can't search for images.

Solution:

Set Unsplash API key:

UNSPLASH_ACCESS_KEY=your-key-here

Get a key at Unsplash Developers.

"Images not loading"

Problem: Selected images don't display.

Solution:

Add Unsplash to allowed image domains in next.config.ts:

images: {
  remotePatterns: [
    {
      protocol: 'https',
      hostname: 'images.unsplash.com',
    },
  ],
}

Production Issues

"Build failed"

Problem: bun run build fails.

Solutions:

Check TypeScript errors:
```
bun run tsc
```
Fix linting errors:
```
bun run lint
```
Ensure database is accessible:

Build runs migrations, so DATABASE_URL must be set.
Use build:only to skip migrations:
```
bun run build:only
```

"App crashes on start"

Problem: Production server crashes immediately.

Solutions:

Check environment variables:

Ensure all required vars are set in production.

Review logs:

# Docker
docker compose logs -f web

# PM2
pm2 logs

# Systemd
journalctl -u quiz-app -f

Verify database connection:
```
psql $DATABASE_URL
```

Getting Help

If you're still stuck:

Check existing issues: GitHub Issues
Create a new issue: Include:
- Error messages (full stack trace)
- Environment (OS, Bun version, Node version)
- Steps to reproduce
- Relevant configuration (without secrets!)
Join discussions: GitHub Discussions

Next Steps

Configuration — Environment variables
RBAC Guide — Permission configuration
Database Guide — Database setup
Deployment Guide — Production deployment

Troubleshooting

On this page