Skip to main content
Applies to: installations crossing 5.2, both editions; SSO-specific actions apply to Enterprise. Also read 5.0 and 5.1 when coming from v4. Use the upgrade-path table to choose a target patch.

Before

Formbricks v5.2 migrates authentication from NextAuth to Better Auth. For most self-hosted instances this is a drop-in upgrade, but if you use SSO (Azure AD / Entra ID, generic OIDC, or SAML) you must re-register the OAuth callback URL at your identity provider before the first v5.2 restart, or SSO sign-in will fail with a redirect-URI mismatch.
All users are signed out once when you upgrade to v5.2. Better Auth takes over session handling and there is no dual-read from the old NextAuth sessions, so the cutover is a one-time forced re-login. Passwords are preserved — existing credential hashes are migrated automatically, so no password reset is needed.

SSO callback URL change (action required for SSO users)

Better Auth serves the OAuth2/OIDC callback at a new path:
  • old (NextAuth): /api/auth/callback/{provider}
  • new (Better Auth): /api/auth/oauth2/callback/{providerId}
Update the redirect / callback URIs at your identity provider to the new path. Replace https://your-domain.com with your instance URL:
Google and GitHub sign-in do not change. They use Better Auth’s built-in social providers, whose callback path (/api/auth/callback/{provider}) is unchanged — nothing to do there.For SAML, only the Jackson connection’s redirect_uri changes. The IdP-side ACS endpoint (/api/auth/saml/callback) is unchanged, so you do not need to reconfigure your IdP’s SAML app.Leave the old /api/auth/callback/* redirect URIs registered through the transition. Keeping them in place is harmless and makes a rollback to v5.1 clean.

OIDC: missing issuer response

A changed callback and issuer_missing are different failures. The older generic OIDC provider requires an RFC 9207 iss response parameter that some identity providers do not send. Setting OIDC_EMAIL_CLAIM does not fix this; it is not a supported configuration option in these releases.
  • For Microsoft Entra, use the dedicated Azure AD provider. Changing providers also requires testing existing-account linking; do not switch a production provider without rehearsal.
  • For generic OIDC, the 5.4 authentication update removes the unconditional missing-iss requirement. Verify sign-in against your actual provider. This does not disable issuer validation when iss is returned.
  • Keep a working administrator sign-in available during rehearsal. Capture redacted callback errors if it fails.

Authentication environment variables

Better Auth introduces two optional variables. Neither is required for a standard upgrade — both fall back to your existing NextAuth configuration:
  • BETTER_AUTH_SECRET — cookie/session signing secret. Falls back to NEXTAUTH_SECRET when unset. On these releases it must be at least 32 characters when set explicitly. Use the value NEXTAUTH_SECRET already holds: a different one invalidates every session and every outstanding invite and verification link.
  • BETTER_AUTH_URL — the auth base URL. Falls back to NEXTAUTH_URL (and then WEBAPP_URL) when unset.
If your instance already sets NEXTAUTH_SECRET and NEXTAUTH_URL (all v5.1 instances do), you can upgrade without adding any new auth variables.
Removed: DISABLE_ACCOUNT_DELETION_SSO_CONFIRMATION no longer exists. Remove it from your environment if you set it; it now has no effect.

Optional new configuration

None of the following is required to run v5.2. Add them only if you want the associated feature.

Hub enrichment (sentiment, emotion, translation)

Hub >= 0.8.0 can classify sentiment and emotion and translate feedback. These are off unless you set a provider and model, and they run in both the Hub API and the hub-worker, so set the variables on both services. Bump your Hub image to >= 0.8.0 (via HUB_IMAGE_REF) to pick up these features.
  • SENTIMENT_PROVIDER, SENTIMENT_MODEL, SENTIMENT_PROVIDER_API_KEY
  • EMOTIONS_PROVIDER, EMOTIONS_MODEL, EMOTIONS_PROVIDER_API_KEY
  • TRANSLATION_PROVIDER, TRANSLATION_MODEL, TRANSLATION_PROVIDER_API_KEY, TRANSLATION_DEFAULT_LANGUAGE
Supported providers: openai, google (AI Studio, needs *_PROVIDER_API_KEY), and google-gemini (Vertex, needs *_GOOGLE_CLOUD_PROJECT / *_LOCATION plus Application Default Credentials).
A provider set without its required credentials crash-loops both Hub containers on startup — it does not degrade gracefully. Set the credentials, or leave the provider unset.

AI taxonomy (beta)

An optional standalone taxonomy service, enabled in Docker Compose with COMPOSE_PROFILES=taxonomy. It shares an internal token with Hub:
  • TAXONOMY_SERVICE_URL (the internal URL to the taxonomy service)
  • HUB_INTERNAL_API_TOKEN, TAXONOMY_SERVICE_TOKEN (strong random secrets)
  • TAXONOMY_LLM_PROVIDER / TAXONOMY_LLM_MODEL / TAXONOMY_LLM_BASE_URL / TAXONOMY_LLM_API_KEY (openai-compatible by default; bedrock and vertex-gemini also supported)
  • TAXONOMY_IMAGE_REF to pin a released image (e.g. :v0.1.0)
Use the target release’s taxonomy setup for the service and secret bindings; do not enable the profile with empty tokens. Generate each missing token with openssl rand -hex 32, then store it in the protected environment file or Secret consumed by those services. Use COMPOSE_PROFILES=qwen,taxonomy to back it with the bundled Qwen/vLLM service.

Bundled Qwen / vLLM runtime

Docker Compose can now run a bundled OpenAI-compatible LLM for self-hosted AI features with COMPOSE_PROFILES=qwen. Tunable via QWEN_VLLM_IMAGE, QWEN_MODEL_ID, QWEN_SERVED_MODEL_NAME, QWEN_MAX_MODEL_LEN, QWEN_MAX_NUM_SEQS, QWEN_GPU_MEMORY_UTILIZATION, QWEN_VLLM_HOST, and QWEN_VLLM_PORT.

OpenTelemetry log export

  • OTEL_LOGS_ENABLED=1 — export Pino application logs via OTLP (off by default; also needs OTEL_EXPORTER_OTLP_ENDPOINT).

During

The credential-account backfill runs in the normal application migration runner; no separate SQL step is needed. On Compose, run formbricks-migrate before Hub migrations and app startup, as shown below. Use the 4.x/5.x maintenance procedure with the selected release’s assets. Add the new SSO callbacks before restart and keep the old ones registered for recovery. Run the target’s application and Hub migrations before starting services; stop on errors.

After

  • Sign in with an existing user through every configured SSO provider, plus password/2FA where enabled.
  • Verify API keys, MCP OAuth and feedback-source connections. Language codes are canonicalized by a data migration; check integrations that compare stored locale values.
  • Run the shared acceptance checks, including old uploads.

Recovery

Keeping the old callback registered allows the identity provider to redirect to an older deployment, but does not undo the authentication database migration. Restore coordinated data and matching images when needed; do not describe a callback change alone as proof that an image-only rollback is safe. See backup and restore. Source: 5.1.5 → 5.2.0.