Skip to main content

Troubleshooting self-hosting

Start with the logs: docker compose logs --tail=200 app. Raise detail with LOG_LEVEL=debug (and set it back afterwards).

The app doesn't start​

  • The log names an environment variable: a required variable is missing or too short — APP_URL (a full URL), DATABASE_URL, AUTH_SECRET (16+ characters), APP_ENCRYPTION_KEY (32+ characters). See Configuration.
  • Can't reach the database: check docker compose ps — the db service must be healthy — and that POSTGRES_PASSWORD hasn't changed since the database was created (the password is set only on the first start of an empty volume).
  • A migration fails: don't edit the database by hand. Restore the backup from before the upgrade, then report the error with the log lines.

Check readiness with curl -fsS http://127.0.0.1:3000/api/ready.

Sign-in problems​

  • Redirected to the wrong address, or cookies don't stick: APP_URL must be the exact public HTTPS address, and the proxy must pass X-Forwarded-Proto (Reverse proxy and TLS).
  • "Too many attempts" for everyone: all requests seem to come from one address. Fix the proxy's X-Forwarded-For handling and TRUST_PROXY_HOPS (Client IP addresses).
  • Single sign-on fails after the provider's page: the redirect URI registered with the provider must match the one in Admin → Authentication exactly; use Test connection to check the issuer.
  • Passkeys stopped working: the domain in APP_URL changed. People add their passkeys again.
  • Locked out of every admin account: create or promote an Owner from the command line (Installation).

Emails don't arrive​

  • MAIL_DRIVER must be smtp; with log, messages only appear in the app log.
  • Look for mail errors in the log (authentication failed, connection refused, TLS errors). Port 465 needs SMTP_SECURE=true; port 587 needs false.
  • Delivered but in spam: set up SPF, DKIM and DMARC for the sender domain (Email).
  • New accounts stuck on Check your email: they need the confirmation email. Fix sending, or turn off Require email verification in Admin → Authentication (Email verification).

Uploads fail​

  • Fail right away for larger files: the proxy's body limit is below the chunk size (nginx's default is 1 MB) — Reverse proxy and TLS.
  • "This file is larger than the … limit": raise the maximum file size in Admin → General → Uploads. A workspace admin can set a lower limit for their workspace.
  • S3: uploads work, downloads don't: browsers must reach the bucket's address; set S3_PUBLIC_ENDPOINT (Storage).
  • S3: chunk size rejected: S3 needs chunks of at least 5 MB.

Webhooks aren't delivered​

  • The instance or the workspace switched webhooks off (Admin → General → API, or the workspace's settings).
  • The target is on a private network: allowed only with Allow webhooks to private network addresses.
  • A webhook that failed 20 times in a row switches itself off; turn it on again after fixing the receiver. See Webhooks.

Still stuck?​

Collect the version (SOL2FLOW_VERSION), the relevant log lines (remove secrets and personal data) and the steps to reproduce, and contact your sol2flow support channel.