Troubleshooting Guide

Common issues and solutions for Refresh App Web.

Deployment Issues

Build Fails in CI/CD

Symptoms: GitHub Actions workflow fails at build step

Causes:

• TypeScript errors

• Missing dependencies

• Environment variables not set

Solutions:

1. Check GitHub Actions logs for specific error

2. Run pnpm check locally to find TypeScript errors

3. Verify AWS SSM parameters exist (see Operations: Environment Management)

4. Check package.json for missing dependencies

5. Review deployment steps in Operations: Deployment Guide

Migration Fails

Symptoms: Database migration fails during deployment

Causes:

• Invalid SQL syntax

• Missing RLS roles

• Network connectivity

Solutions:

1. Review migration SQL in drizzle/migrations/

2. Verify database is accessible

3. Check role permissions in Neon

4. Run migration manually to see detailed error

Secrets Not Loading

Symptoms: Application errors due to missing secrets

Causes:

• Secrets not uploaded to Cloudflare

• AWS SSM parameters missing

• Environment mismatch

Solutions:

1. Re-upload secrets: ./scripts/bulk-upload-secrets.sh

2. Verify parameters in AWS SSM console

3. Check parameter names match expected format

Authentication Issues

OAuth Login Fails

Symptoms: Users can't log in via Google/Microsoft

Causes:

• Invalid OAuth credentials

• Redirect URI mismatch

• AUTH_SECRET not set

Solutions:

1. Verify OAuth client ID/secret in Google/Microsoft console

2. Check redirect URI matches: https://app.refresh.tech/auth/callback/google

3. Ensure AUTH_SECRET is set in environment

Session Not Persisting

Symptoms: Users logged out after page refresh

Causes:

• Cookie settings incorrect

• Database session not created

• AUTH_SECRET changed

Solutions:

1. Check cookie settings (httpOnly, secure, sameSite)

2. Verify session table exists in database

3. Clear cookies and re-login

Database Issues

RLS Denying Access

Symptoms: Queries return no data despite data existing

Causes:

• JWT not containing correct tenant_id

• RLS policy misconfigured

• User doesn't belong to tenant

Solutions:

1. Decode JWT and verify tenant_id claim

2. Check RLS policies in Neon SQL editor

3. Verify user has tenant membership

Connection Timeouts

Symptoms: Database queries timing out

Causes:

• Network connectivity

• Database overloaded

• Connection string incorrect

Solutions:

1. Test connection: psql $WRITE_DATABASE_URL -c "SELECT 1"

2. Check Neon dashboard for database status

3. Verify connection string format

Performance Issues

Slow Page Loads

Symptoms: Pages take >3 seconds to load

Causes:

• Large database queries

• No caching

• Large bundle size

Solutions:

1. Review database queries for N+1 problems

2. Enable session caching

3. Run bundle analysis: pnpm build (check dist/bundle-analysis.html)

4. Lazy load heavy components

High Memory Usage

Symptoms: Workers hitting memory limits

Causes:

• Large data processing in Workers

• Memory leaks

• Too many concurrent operations

Solutions:

1. Process data in chunks

2. Review code for circular references

3. Use streaming where possible

Application Errors

500 Internal Server Error

Symptoms: Users see 500 error page

Causes:

• Unhandled exception

• Database error

• Missing environment variable

Solutions:

1. Check Wrangler logs: npx wrangler tail --env production

2. Review error in PostHog

3. Check all required env vars are set

404 Not Found

Symptoms: Page not found errors

Causes:

• Route doesn't exist

• Build didn't include page

• Typo in URL

Solutions:

1. Verify route exists in src/routes/

2. Check build output includes route

3. Review routing configuration

Common Error Messages

"Failed to fetch"

Cause: Network request failed

Solution:

1. Check API endpoint exists

2. Verify CORS headers for cross-origin requests

3. Check network connectivity

"Unauthorized"

Cause: Missing or invalid authentication

Solution:

1. Verify user is logged in

2. Check session is valid

3. Ensure JWT is being sent

"Forbidden"

Cause: User lacks permissions

Solution:

1. Check user role

2. Verify tenant membership

3. Review affordance restrictions

Escalation

If issue persists:

1. Check documentation - Review related docs

2. Search existing issues - GitHub issues, PostHog errors

3. Contact team - Slack #dev-app-web channel

4. Create incident - For production issues

Related Documentation

• Monitoring

• Deployment Guide

• Operations: Environment Management

---

Last updated: October 2025