Upgrade to Formbricks v6

​

What runs where

​

Before the maintenance window

• Rehearse with a restored copy of the installation. Measure migrations, backfill, verification, and restoration time; use those measurements to communicate the maintenance window.
• Pin the target Formbricks image by digest and the matching chart/Compose files. Preserve the current images, chart, values, secrets, and volume names. Do not combine this change with a PostgreSQL major upgrade, a storage migration, or unrelated Hub/Cube changes.
• Treat the Helm chart version and application image version as separate pins. A chart-only patch can keep the same Formbricks appVersion; verify both values and the rendered image before upgrading.
• Prepare private SpiceDB connectivity, dedicated datastore credentials, its reviewed version, and completed datastore migrations. Retain existing operator ownership; never install a second operator over an existing cluster-wide operator. See SpiceDB operations.

​

Perform the upgrade

formbricks-authzed-prepare --backup-confirmed --writers-stopped

​

Docker and one-click

docker compose --profile authzed-ops run --rm --no-deps \
  --entrypoint formbricks-authzed-prepare authzed-ops \
  --backup-confirmed --writers-stopped

​

Helm and GitOps

apiVersion: batch/v1
kind: Job
metadata:
  name: formbricks-v6-prepare
spec:
  backoffLimit: 0
  activeDeadlineSeconds: 7200
  template:
    spec:
      restartPolicy: Never
      automountServiceAccountToken: false
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
      containers:
        - name: prepare
          image: ghcr.io/formbricks/formbricks@sha256:<target-image-digest>
          command: ["formbricks-authzed-prepare"]
          args: ["--backup-confirmed", "--writers-stopped"]
          securityContext:
            allowPrivilegeEscalation: false
            capabilities:
              drop: ["ALL"]
          envFrom:
            - secretRef:
                name: formbricks-maintenance-env
          # Inert placeholders for the shared environment check. Preparation never reads them, and they are
          # not application secrets: never reuse these values in a running installation.
          env:
            - { name: ENCRYPTION_KEY, value: maintenance-unused }
            - { name: CUBEJS_API_SECRET, value: maintenance-unused }
            - { name: CUBEJS_API_URL, value: "http://localhost" }
            - { name: HUB_API_KEY, value: maintenance-unused }
            - { name: HUB_API_URL, value: "http://localhost" }
            - { name: REDIS_URL, value: "redis://localhost" }

• DATABASE_URL
• AUTHZED_ENABLED=true, AUTHZED_ENDPOINT, AUTHZED_TOKEN, AUTHZED_SYSTEM_KEY, AUTHZED_INSECURE, and AUTHZED_CONSISTENCY=fully_consistent
• WEBAPP_URL, in every case. Preparation runs the database migrations, and the OAuth resource-link data migration (eng_2343_backfill_oauth_resource_links, first released in 5.4.0) derives each MCP OAuth client’s resource link from it. Whenever that migration runs on a database with MCP OAuth clients, as in any upgrade from before 5.4.0, preparation stops with upgrade_database_migration_failed without it.

​

Exit checklist

• formbricks-authzed-prepare exited 0, including its two clean full audits, and the v6 migration acknowledgement is set only for this prepared upgrade.
• The running image ID, chart values, schema, outbox, and a fresh formbricks-authzed upgrade check match the reviewed target.
• Allowed and denied users, a scoped API key, organization/workspace lists, and a grant revocation work from a fresh browser session; an old tab recovers after a hard refresh.

​

Results and recovery

{"status":"prepared","code":"upgrade_prepared","restartRequired":true}

• "reason":"timeout" and timeoutSeconds: the step ran out its time limit. It did not report a failure, so the code names the step, not a problem in it. Raise the limit and run preparation again.
• cause and retryable: the step’s own error code, such as authzed_unavailable, and whether that error is transient. Retry a "retryable":true result once its cause, such as SpiceDB availability, has recovered.

​

Diagnose migration failures privately

​

Later v6 upgrades

​

Survey visibility

1. Once every container or pod runs the new version, check durable delivery and replay any dead-lettered survey events. The migration adds the survey trigger while the previous version may still be delivering outbox events, and that version dead-letters the survey event type it does not know. A dead-lettered survey revocation makes every enforced authorization check fail closed until it is replayed:
   formbricks-authzed outbox status
   formbricks-authzed outbox replay
   formbricks-authzed outbox drain
   
   replay resets every unresolved dead letter, so investigate any that are not survey events first. See AuthZed operations for how to list them.
2. After the upgrade, repair the survey scope and mark it ready. This runs the repair, then two further dry runs, and sets the marker only if both come back clean:
   formbricks-authzed backfill --scope=survey --apply --mark-ready
   
3. Confirm formbricks-authzed upgrade check reports scopes.survey as ready.