> ## Documentation Index
> Fetch the complete documentation index at: https://docs.folksbase.joselito.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common deployment issues and how to fix them.

## Zod Validation Error on Startup

**Symptom:** The API crashes immediately with an error like:

```
Error: Invalid environment variables:
  - DATABASE_URL: Required
  - REDIS_URL: Required
```

**Cause:** Missing or malformed environment variables. Every env var is validated with Zod at startup.

**Fix:**

1. Check your `.env` file (local) or platform env var settings (Render/Vercel)
2. Compare against `.env.example` in the relevant app directory
3. Make sure URLs are valid (include `https://`) and strings aren't empty

## ENCRYPTION\_KEY Validation Failure

**Symptom:** API crashes with:

```
ENCRYPTION_KEY: Must be a 64-char hex string (32 bytes)
```

**Cause:** The `ENCRYPTION_KEY` must be exactly 64 hexadecimal characters.

**Fix:** Generate a valid key:

```bash theme={"dark"}
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

## CORS Errors in the Browser

**Symptom:** API requests from the frontend fail with CORS errors in the browser console.

**Cause:** The `FRONTEND_URL` env var on the API doesn't include the frontend's origin.

**Fix:** Set `FRONTEND_URL` to match your frontend URL exactly. For multiple origins, use comma-separated values:

```bash theme={"dark"}
FRONTEND_URL=https://folksbase.joselito.dev,https://staging.folksbase.dev
```

Each origin must start with `http://`, `https://`, or `*.` (wildcard).

## Render Health Check Failing

**Symptom:** Render shows the service as unhealthy and keeps restarting it.

**Cause:** The `/health` endpoint checks both the database (Neon) and Redis connections. If either is unreachable, it returns a 503.

**Fix:**

1. Check that `DATABASE_URL` and `REDIS_URL` are correct in Render's env vars
2. Verify your Neon database is active (free tier databases pause after inactivity)
3. Verify your Upstash Redis instance is running
4. Check Render logs for the specific error in the health check response

## Stale Schema After Database Changes

**Symptom:** `db:push` or `db:migrate` doesn't detect your schema changes.

**Cause:** Drizzle reads from `dist/` (compiled JS), not `src/` (TypeScript). If you run `drizzle-kit` directly, it reads stale compiled files.

**Fix:** Always use the pnpm scripts — they run `tsc` before drizzle-kit:

```bash theme={"dark"}
# Correct
pnpm --filter @folksbase/db db:push

# Wrong — reads stale dist/
npx drizzle-kit push
```

## Build Fails in Monorepo

**Symptom:** Vercel or Render build fails because a shared package can't be found.

**Cause:** The build command isn't resolving monorepo dependencies correctly.

**Fix:**

* On Vercel: set the root directory to `apps/web` and let Turborepo handle dependency resolution
* On Render: the `render.yaml` build command (`pnpm install && pnpm --filter @folksbase/api build`) handles this correctly
* Make sure `pnpm-lock.yaml` is committed — both platforms use `--frozen-lockfile`

## Neon Database Connection Timeout

**Symptom:** API requests hang or timeout when querying the database.

**Cause:** The project uses Neon's HTTP driver, which works over standard HTTPS. Connection issues are usually network-related.

**Fix:**

1. Check that the Neon database isn't paused (free tier pauses after inactivity)
2. Verify the `DATABASE_URL` is correct and includes the correct project/branch
3. Check Neon's status page for outages
4. Remember: the HTTP driver is intentional for Render compatibility — don't switch to the WebSocket driver

## Playwright E2E Tests Failing in CI

**Symptom:** E2E tests pass locally but fail in CI.

**Cause:** Usually a missing env var or the preview URL isn't ready yet.

**Fix:**

1. Ensure `E2E_USER_EMAIL` and `E2E_USER_PASSWORD` are set in CI secrets (real Supabase credentials)
2. Verify `PLAYWRIGHT_BASE_URL` points to the correct preview URL
3. Check that the Vercel preview deployment finished before tests started

## Existing Plaintext Keys After Enabling Encryption

**Symptom:** Settings with `resend_api_key` fail to load after deploying the encryption feature.

**Cause:** Existing plaintext keys in the database can't be decrypted because they were never encrypted.

**Fix:** Either:

* Have users re-enter their Resend API keys after deploying (simplest)
* Run a one-time migration script to encrypt existing plaintext values