Skip to main content

Troubleshooting

Common issues and how to solve them.

Builder Platform Issues​

Cannot sign in / "Invalid credentials"​

Symptoms: Login fails with "Invalid credentials" even with correct password.

Causes:

  • Wrong email or password
  • Account locked after 5 failed attempts
  • Account suspended by admin

Solutions:

  1. Double-check email and password (case-sensitive)
  2. If locked, wait 15 minutes and try again
  3. Contact admin if account is suspended

"Project not found" (but it exists)​

Symptoms: API returns 404 for a project you created.

Causes:

  • Not a member of the project
  • Using wrong account
  • Project was deleted

Solutions:

  1. Check you're signed in as the correct user
  2. Ask project owner to add you as a member
  3. Verify project ID is correct

API token not working​

Symptoms: API returns 401 "Unauthorized" with a valid-looking token.

Causes:

  • Token expired
  • Token revoked
  • Token pinned to different project
  • Missing required scope

Solutions:

  1. Check token expiry date (GET /account/tokens)
  2. Create a new token if expired/revoked
  3. Ensure token has required scopes (read, write, generate)
  4. If pinned to project, use it only for that project

Validation fails with "Unknown error"​

Symptoms: POST /projects/{id}/validate returns a generic error.

Causes:

  • Spec is malformed JSON
  • Very large spec (> 10 MB)
  • Internal validation bug

Solutions:

  1. Validate your JSON (use jq or JSONLint)
  2. Check spec size: GET /projects/{id}/spec and check response size
  3. Try validating in smaller parts (entities, auth, etc. separately)
  4. Report the issue with spec (redacted if needed)

Generation Issues​

Generation takes forever / times out​

Symptoms: POST /projects/{id}/generate/preview or download never completes.

Causes:

  • Very large project (many entities)
  • Server overloaded
  • Network timeout

Solutions:

  1. Try again (transient issue)
  2. Use preview first to check size
  3. Reduce project complexity if possible
  4. Contact support if persistent

Symptoms: GET /projects/{id}/generate/download returns 404.

Causes:

  • Download link expires after 30 days
  • Generation was deleted

Solutions:

  1. Regenerate: POST /projects/{id}/generate/preview then download
  2. Downloads are free—regenerate as needed

ZIP is corrupted / won't extract​

Symptoms: Downloaded ZIP won't open or extract.

Causes:

  • Incomplete download
  • Network issue during download

Solutions:

  1. Check file size matches Content-Length header
  2. Download again
  3. Try a different extraction tool
  4. Contact support if file is consistently corrupted

Generated Project Issues​

"docker compose up" fails immediately​

Symptoms: Containers crash on startup.

Causes:

  • Docker not running
  • Ports already in use (8000, 5432)
  • Missing .env file
  • Invalid environment variables

Solutions:

  1. Check Docker Desktop is running
  2. Stop other services using ports: lsof -i :8000 (macOS/Linux) or netstat -ano | findstr :8000 (Windows)
  3. Copy .env.example to .env and fill in required values
  4. Check logs: docker compose logs

"alembic upgrade head" fails​

Symptoms: Database migration fails.

Causes:

  • Database not running
  • Wrong DATABASE_URL
  • Previous migration left in bad state
  • PostgreSQL version too old (< 14)

Solutions:

  1. Check PostgreSQL is running: docker compose ps
  2. Verify DATABASE_URL in .env (check host, port, credentials)
  3. Check current migration state: alembic current
  4. If stuck, drop database and recreate: 
    docker compose down -v
    docker compose up -d db
    alembic upgrade head
  5. Ensure PostgreSQL 14+ is used

Generated API returns 500 errors​

Symptoms: All or most endpoints return 500 Internal Server Error.

Causes:

  • Database connection failed
  • Missing required environment variables
  • Migration not applied
  • Bug in generated code

Solutions:

  1. Check logs: docker compose logs api
  2. Verify DATABASE_URL is correct
  3. Run migrations: alembic upgrade head
  4. Check all required env vars are set (see .env.example)
  5. Test database connection: docker compose exec api python -c "from app.db import engine; print(engine)"

Authentication doesn't work in generated project​

Symptoms: /auth/register or /auth/login fails in generated project.

Causes:

  • Missing AUTH_JWT_SECRET
  • Wrong SMTP/SMS credentials
  • Email/SMS provider unreachable

Solutions:

  1. Generate a secret: python -m app.auth.keys (in generated project)
  2. Set AUTH_JWT_SECRET in .env
  3. For email: verify SMTP settings with python -m app.auth.test_smtp (if available)
  4. Check logs for specific provider errors

Payments module not working​

Symptoms: POST /payments fails or webhook not received.

Causes:

  • Missing Stripe/Razorpay credentials
  • Worker not running
  • Database payments schema not created

Solutions:

  1. Check STRIPE_SECRET_KEY or RAZORPAY_KEY_SECRET in .env
  2. Start worker: docker compose up -d worker
  3. Check migration applied: alembic current (should show 0003_payments or later)
  4. Check webhook secret: STRIPE_WEBHOOK_SECRET or RAZORPAY_WEBHOOK_SECRET
  5. For local testing, use Stripe CLI: stripe listen --forward-to localhost:8000/payments/webhook

File uploads rejected / "Malware scanner down"​

Symptoms: File uploads fail with scanner error.

Causes:

  • ClamAV not running
  • ClamAV signatures not updated
  • Scanner out of memory

Solutions:

  1. Check ClamAV is running: docker compose ps clamav
  2. Wait for signature updates (can take 5-10 minutes on first start)
  3. Check logs: docker compose logs clamav
  4. Increase memory: add to docker-compose.yml: 
    clamav:
      deploy:
        resources:
          limits:
            memory: 2G

Keycloak won't start​

Symptoms: Keycloak container crashes or never becomes ready.

Causes:

  • Insufficient memory (needs 512MB+)
  • Port 8080 already in use
  • Database not ready

Solutions:

  1. Check logs: docker compose logs keycloak
  2. Increase memory in Docker Desktop settings (4GB+ recommended)
  3. Change port in docker-compose.yml if 8080 is taken
  4. Ensure keycloak-db is healthy: docker compose ps

Dashboard Issues​

Dashboard shows blank page​

Symptoms: Frontend loads but shows nothing.

Causes:

  • API not reachable
  • CORS issue
  • JavaScript error

Solutions:

  1. Check browser console for errors (F12)
  2. Verify API is running: curl https://api.builder.dumbpotato.com/health
  3. Check BUILDER_CORS_ORIGINS includes frontend URL
  4. Clear browser cache and reload

"Network error" on every request​

Symptoms: Dashboard can't reach API.

Causes:

  • API not running
  • Wrong API URL in frontend
  • CORS misconfiguration

Solutions:

  1. Check API is running: https://api.builder.dumbpotato.com
  2. Verify frontend points to correct API (check frontend/.env or config)
  3. Check browser console for CORS errors
  4. Ensure BUILDER_CORS_ORIGINS=["https://app.builder.dumbpotato.com"] in API

Changes don't save / "Version conflict"​

Symptoms: Save fails with "version conflict" or 409 error.

Causes:

  • Optimistic locking: project was modified by someone else
  • Multiple tabs open
  • Stale page

Solutions:

  1. Reload the page to get latest version
  2. Copy your changes before reloading (they'll be lost)
  3. Re-apply changes after reload
  4. Close duplicate tabs

Deployment Issues (Generated Project)​

GitHub Actions workflow fails​

Symptoms: CI/CD pipeline fails during build or deploy.

Causes:

  • Missing secrets
  • Wrong AWS/Azure/GCP credentials
  • Terraform state locked
  • Migration failed

Solutions:

  1. Check all required secrets are set in GitHub repo settings
  2. Verify cloud credentials are valid (try manually)
  3. Unlock Terraform state: terraform force-unlock <lock-id>
  4. Check workflow logs for specific error
  5. See generated deploy/DEPLOYMENT.md for troubleshooting

Terraform apply fails​

Symptoms: terraform apply fails with resource errors.

Causes:

  • Insufficient permissions
  • Resource already exists
  • Invalid configuration
  • State out of sync

Solutions:

  1. Check IAM permissions (see deploy/DEPLOYMENT.md)
  2. Import existing resource: terraform import <resource> <id>
  3. Validate config: terraform validate
  4. Refresh state: terraform refresh
  5. Destroy and recreate (if safe): terraform destroy && terraform apply

Deployed API returns 502 / 504​

Symptoms: Deployed API shows gateway errors.

Causes:

  • Container not starting
  • Health check failing
  • Database connection failed
  • Out of memory

Solutions:

  1. Check container logs (AWS CloudWatch, Azure Monitor, GCP Logging)
  2. Verify DATABASE_URL is correct for cloud database
  3. Check health endpoint: curl https://your-api.com/health
  4. Increase memory/CPU in Terraform config
  5. Check security groups allow egress to database

Performance Issues​

API is slow​

Symptoms: Requests take > 1 second.

Causes:

  • Database not indexed
  • N+1 query problem
  • Large spec loaded every time
  • No connection pooling

Solutions:

  1. Check slow query log in PostgreSQL
  2. Add indexes to foreign keys and frequent lookups
  3. Use pagination (limit/offset)
  4. Verify connection pooling is enabled (SQLAlchemy pool settings)

Generated project is slow​

Symptoms: Generated API responds slowly.

Causes:

  • Many relations (joins)
  • Large response payloads
  • No database indexes
  • Insufficient resources

Solutions:

  1. Use database indexes (generated migrations include some, add more if needed)
  2. Limit response size (pagination, field selection)
  3. Use database query logging to find slow queries
  4. Scale up resources (more CPU/RAM)

Getting Further Help​

Before Contacting Support​

  1. Check this troubleshooting guide
  2. Check FAQ
  3. Check the dashboard validation output if validation issue
  4. Search existing GitHub issues
  5. Try the issue in a fresh project (isolate the problem)

What to Include in Support Requests​

  • Builder platform issues:

    • Your account email (if safe to share)
    • Project ID (if relevant)
    • Steps to reproduce
    • Error messages (exact text or screenshot)
    • What you've tried

  • Generated project issues:

    • Generated project spec (redact secrets!)
    • Error logs (docker compose logs)
    • Environment (local dev, AWS, Azure, GCP)
    • Docker version, PostgreSQL version
    • What you've tried

Contact Support​

For AI agents: This is the troubleshooting guide for common issues. Prerequisites: Issue encountered. Related: FAQ, the dashboard validation output. Common tasks: Users come here when something isn't working, scan for their specific issue.

Last updated on