Skip to main content
Find solutions to common issues you might encounter when using Soundcheck.

​
Mobile app

Symptoms: App immediately closes after splash screen.Solutions:
  1. Clear Expo cache: 
    npx expo start --clear
  2. Delete node_modules and reinstall: 
    rm -rf node_modules
npm install
  3. Check for missing environment variables in .env
Symptoms: Google/Apple sign-in redirects but doesn’t complete.Solutions:
  1. Verify scheme: "soundcheck" in app.config.js
  2. Rebuild the app (OTA updates don’t include native changes): 
    npx eas build --platform ios --profile development
  3. Check Clerk Dashboard OAuth configuration
  4. Ensure redirect URLs match exactly
Symptoms: All API calls fail with authentication errors.Solutions:
  1. Check if Clerk token is being sent:
    • Open React Native debugger
    • Check Network tab for Authorization header
  2. Verify EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY is correct
  3. Sign out and sign back in to refresh token
  4. Check if token has expired (1 hour default)
Symptoms: npm run ios hangs or fails.Solutions:
  1. Install Xcode Command Line Tools: 
    xcode-select --install
  2. Open Xcode and accept license agreement
  3. Reset simulator: 
    xcrun simctl shutdown all
xcrun simctl erase all
Symptoms: App can’t connect to local API.Solutions:
  1. Use 10.0.2.2 instead of localhost for Android emulator
  2. Or use your machine’s IP address
  3. Ensure API is running and accessible
Symptoms: EAS build fails with “no space left on device”.Solutions:
  1. Run cleanup script: 
    ./cleanup-disk-space.sh
  2. Manual cleanup: 
    rm -rf ~/Library/Developer/Xcode/DerivedData/*
xcrun simctl delete unavailable
  3. Use cloud builds instead: 
    npx eas build --platform ios --profile production

​
Web app

Symptoms: npm run build fails with import errors.Solutions:
  1. Clear Next.js cache: 
    rm -rf .next
npm run build
  2. Delete and reinstall dependencies: 
    rm -rf node_modules package-lock.json
npm install
  3. Check for typos in import paths
Symptoms: process.env.NEXT_PUBLIC_* returns undefined.Solutions:
  1. Ensure file is named .env.local (not .env)
  2. Prefix client-side vars with NEXT_PUBLIC_
  3. Restart dev server after adding new variables
  4. Check for syntax errors in .env.local
Symptoms: Sign-in redirects back to sign-in page repeatedly.Solutions:
  1. Check CLERK_SECRET_KEY is set (server-side)
  2. Clear browser cookies and local storage
  3. Verify Clerk Dashboard redirect URLs include localhost:3000
Symptoms: Console shows “Access-Control-Allow-Origin” errors.CORS uses an origin allowlist. The API only allows browser requests from origins listed in CORS_ORIGINS.Solutions:
  1. Check that CORS_ORIGINS includes your browser’s origin. For local dev the defaults cover http://localhost:3000 (Next.js), http://localhost:8081 (Expo Web / Metro), and http://localhost:8082 (legacy)
  2. If you’re running the web app on a non-default port, add it to CORS_ORIGINS in your API .env
  3. In deployed environments, CORS_ORIGINS must be explicitly set (e.g. https://app.soundchecklive.io)
  4. Native mobile apps (iOS/Android) are not affected by CORS — only browser-based clients
Symptoms: Red squiggly lines but npm run build works.Solutions:
  1. Restart TypeScript server: Cmd+Shift+P → “TypeScript: Restart TS Server”
  2. Check tsconfig.json paths match your setup
  3. Run npm run typecheck to see actual errors

​
API

Symptoms: docker compose up fails or containers exit immediately.Solutions:
  1. Check Docker Desktop is running
  2. View container logs: 
    docker compose logs api
docker compose logs db
  3. Check port conflicts (5433, 8080): 
    lsof -i :5433
lsof -i :8080
  4. Reset Docker: 
    docker compose down -v
docker compose up -d
Symptoms: API logs show “connection refused” to PostgreSQL.Solutions:
  1. Ensure database container is running: 
    docker compose ps
  2. Check DATABASE_URL uses correct port (5433 for Docker)
  3. Wait for database to be ready (can take 10-15 seconds)
  4. Check database logs: 
    docker compose logs db
Symptoms: prisma migrate deploy errors.Solutions:
  1. Ensure database is accessible
  2. Check for pending migrations: 
    npx prisma migrate status
  3. Reset database (dev only): 
    npx prisma migrate reset
  4. Check schema syntax: 
    npx prisma validate
Symptoms: All authenticated requests return 401.Solutions:
  1. Verify CLERK_SECRET_KEY matches Clerk Dashboard
  2. Check token is being sent in Authorization: Bearer <token> header
  3. Ensure Clerk instance is correct (test vs production)
  4. Check if token has expired
Symptoms: Clerk/Stripe webhooks return 400/401.Solutions:
  1. Verify webhook secret matches Dashboard
  2. For Stripe: Check STRIPE_WEBHOOK_SECRET
  3. For Clerk: Verify signing secret in Clerk Dashboard
  4. Ensure request body is raw (not parsed JSON)

​
Infrastructure

Symptoms: terraform plan fails with Azure auth errors.Solutions:
  1. Re-authenticate with Azure: 
    az login
  2. Check service principal credentials: 
    az account show
  3. Verify ARM_* environment variables are set
Symptoms: App Service can’t read secrets from Key Vault.Solutions:
  1. Verify managed identity is assigned to App Service
  2. Check RBAC permissions on Key Vault
  3. Ensure private endpoint is configured
  4. Check private DNS zone is linked to VNet
Symptoms: Azure VPN Client won’t connect.Solutions:
  1. Re-import azurevpnconfig.xml from 1Password
  2. Ensure Azure AD account is provisioned
  3. Check VPN gateway is running in Azure Portal
  4. Try disconnecting and reconnecting

​
CI/CD

Symptoms: Workflow shows “queued” indefinitely.Solutions:
  1. Check self-hosted runner is online
  2. Verify runner labels match workflow runs-on
  3. Check GitHub Actions service status
Symptoms: iOS/Android build fails with signing errors.Solutions:
  1. Check EXPO_TOKEN is set in GitHub Secrets
  2. Run credentials setup: 
    npx eas credentials
  3. For iOS: Ensure certificates aren’t expired
  4. For Android: Verify keystore is configured
Symptoms: “Error acquiring the state lock”.Solutions:
  1. Wait for other deployment to complete
  2. If stuck, force unlock (use with caution): 
    terraform force-unlock <lock-id>
  3. Check Azure Blob Storage for lock file

​
Getting help

If your issue isn’t covered here:
  1. Search existing issues on GitHub
  2. Check logs for specific error messages
  3. Ask in Slack #soundcheck-dev
  4. Open a GitHub issue with:
    • Steps to reproduce
    • Expected vs actual behavior
    • Relevant logs/screenshots
    • Environment details (OS, versions)