Diagnose a blocked migration and choose between repair and restore.
Keep maintenance active when an upgrade fails. Record the failed step, source and target images,
and sanitized error code. Retry only after checking for partial changes and concurrent migration runners.
A completed migration is not the final acceptance check. Return to your deployment recipe before
restarting writers or reopening traffic.
If a migration fails
From Formbricks 5.3 on, one runner applies every database migration in order: the formbricks-migrate service on
Docker Compose, the formbricks-migration Job on Kubernetes (the application pods themselves when the chart sets
migration.enabled: false), or formbricks-authzed-prepare during a v5 to v6 upgrade. When a migration fails,
the runner stops and no later migration runs. A failed schema migration then blocks every later run until you
resolve it; a failed data migration is retried on the next run.
Do not delete volumes, restore a backup or roll the images back before you know which migration failed and
why. Most failures are fixed in place. The output below can contain SQL and data from your instance, so keep
it out of public issues.
Open a SQL session
The steps below run SQL as the user that owns the Formbricks tables:
If your PostgreSQL pod has a different name, run kubectl get pods -n formbricks to find it.
With an external or managed PostgreSQL, connect with psql as the user in MIGRATE_DATABASE_URL, or in
DATABASE_URL if you do not set it. The migrations themselves need a direct or session-pooled connection: a
transaction-mode pooler such as PgBouncer can split their session settings across server connections.
1. Find the failed migration
The runner’s output names it. docker compose run … formbricks-migrate and the update script print it to your
terminal; docker compose logs --tail=200 formbricks-migrate has it only when the service ran under
docker compose up. On Kubernetes, read kubectl logs -n formbricks job/formbricks-migration (by default the
chart deletes the Job 300 seconds after it fails). A first failure prints Schema migration batch failed: with
every migration in that batch; the error names the failed one as Migration name:, or as migration_name="…"
when the real error was hidden. Every run after that stops with P3009 and names it again. If you have no log,
including with formbricks-authzed-prepare, which prints only upgrade_database_migration_failed (plus
"reason":"timeout" when the step ran out its time limit rather than failing), the database always knows:
SELECT migration_name, started_at FROM "_prisma_migrations"WHERE finished_at IS NULL AND rolled_back_at IS NULL;
If that returns no row but the log says Data migration … failed, see Data migrations
below. If the log just stops without an error, the runner was stopped (Compose stops it after 300 seconds) and
its last statement may still be running in PostgreSQL: check that first, as step 3 describes.
2. Find the real error
The runner’s error usually shows it after Database error:. If it shows only current transaction is aborted, commands ignored until end of transaction block, the migration runs in a transaction of its own and the
real error was hidden. Find it in the PostgreSQL log, on the
ERROR line just before that one:
On a managed service, use your provider’s database log. canceling statement due to lock timeout is the most
common cause: another session held a lock on the table the migration changes, for example a long-running query,
a backup, or an old Formbricks pod still running. Stop it, or retry at a quieter time. If the error itself lists
recovery steps, as some migrations’ guards do, follow those.
3. Check what the migration left behind
First make sure nothing is still running it. On Compose, the runner has exited. On Kubernetes, the Job has
finished retrying (kubectl wait -n formbricks --for=condition=Failed job/formbricks-migration --timeout=10m
returns, or the Job is gone). With migration.enabled: false the application pods are the runner and retry on
every restart, so scale them to 0 (kubectl scale deploy -n formbricks formbricks --replicas=0) until step 4. A
statement keeps running in PostgreSQL after its runner is stopped, so also list what the database is still
running:
SELECT pid, now() - query_start AS running_for, left(query, 80) AS query, pid IN (SELECT pid FROM pg_locks WHERE locktype = 'advisory' AND objid = 72707369) AS migration_lockFROM pg_stat_activityWHERE datname = current_database() AND state IS DISTINCT FROM 'idle' AND pid <> pg_backend_pid();
migration_lock marks a schema migration: Prisma holds that lock while it applies one. Data migrations take no
such lock, so also look for statements on the tables the migration changes. Wait for every migration statement
to end.Then read the failed migration’s file. A released migration never changes, so the copy in your image is the one
that ran:
migration_name='<the name from step 1>'docker compose run --rm --no-deps --entrypoint cat formbricks-migrate \ "packages/database/dist/migration/${migration_name}/migration.sql"
It is also on GitHub under any release that ships it, for example
https://github.com/formbricks/formbricks/blob/6.0.2/packages/database/migration/<migration_name>/migration.sql.
The runner printed an error, and the whole file is one BEGIN; … COMMIT; block, with no statement before
BEGIN; or after COMMIT;: PostgreSQL rolled the whole file back, so there is nothing to undo. A file that
commits a block and then runs more statements, such as 20250911192630_remove_deprecated_fields_and_tables,
belongs under the next case.
Otherwise, including any migration whose runner was stopped instead of printing an error: the statements
before the failing one may have taken effect, even inside a BEGIN; … COMMIT; block. For a stopped runner,
possibly every statement in the file did: a file Prisma sends as one string runs to its end without a client.
Check which did (\d "Table" for schema changes, a SELECT for data) and undo those before you continue. If
the new version is already serving, stop it first (docker compose stop formbricks, or scale the Deployment to
0) and keep it stopped until you run the migrations again. Undoing a DROP means recreating the object so the
retry can drop it again; if a change cannot be undone, such as an UPDATE whose old values are gone, stop and
restore the pre-upgrade backup instead. You need not undo:
IF NOT EXISTS, IF EXISTS and CREATE OR REPLACE statements are safe to repeat, apart from a failed
CREATE INDEX CONCURRENTLY. That leaves an invalid index which IF NOT EXISTS then skips: list invalid
indexes with SELECT indexrelid::regclass FROM pg_index WHERE NOT indisvalid; and drop only those the
migration’s file creates, with SET lock_timeout = 0; and then DROP INDEX CONCURRENTLY.
An UPDATE, INSERT or DELETE is safe to repeat only if running it twice changes nothing.
4. Mark it rolled back and run the migrations again
Once the cause is fixed, mark the failed migration rolled back. This is what
prisma migrate resolve --rolled-back does. It should report UPDATE 1; UPDATE 0 means the name is wrong or
the migration is not recorded as failed:
UPDATE "_prisma_migrations" SET rolled_back_at = now()WHERE migration_name = '<migration_name>' AND finished_at IS NULL AND rolled_back_at IS NULL;
Then run the migrations again:
One-Click / Docker Compose
Kubernetes
docker compose run --rm --no-deps formbricks-migrate
The service stops the runner after 300 seconds. If a migration needs longer, run it without that limit:
docker compose run --rm --no-deps formbricks-migrate "node packages/database/dist/scripts/apply-migrations.js"
During a v5 to v6 upgrade, re-run formbricks-authzed-prepare as the
v6 maintenance upgrade guide describes instead.
Delete the failed Job, then run the same helm upgrade (or Argo CD sync) again. Helm does not re-run a Job
that still exists, and refuses to change one (field is immutable):
With migration.enabled: false, scale the Deployment back up instead; its pods run the migrations on start.Otherwise, if you scaled the Deployment to 0 in step 3, scale it back up once the Job succeeds
(kubectl scale deploy -n formbricks formbricks --replicas=<your count>). helm upgrade restores the count
only when autoscaling.enabled is false and deployment.replicas is set, and an autoscaler does not scale up
from 0.During a v5 to v6 upgrade, delete and re-create the formbricks-v6-prepare Job as the
v6 maintenance upgrade guide describes instead.
Data migrations
Most data migrations run in a transaction of their own and leave nothing behind when they fail; the large ones
commit in batches and are written to resume where they stopped. Either way the runner records the failure and
retries the migration on the next run: fix the cause and run the migrations again. The exception is
Migration is pending. Please resolve the issue manually., left by an interrupted run of a version before 5.3.
Make sure nothing is still running it (step 3), then mark it failed so the next run retries it:
SELECT name, status, started_at FROM "DataMigration" WHERE status <> 'applied';UPDATE "DataMigration" SET status = 'failed' WHERE name = '<name>' AND status = 'pending';
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Documentation - Formbricks","colors":{"primary":"#00C4B8","light":"#00C4B8","dark":"#00C4B8"},"logo":{"light":"https://mintcdn.com/formbricks/wqEbm3FT1QK_6-vL/images/logo-light.svg?fit=max\u0026auto=format\u0026n=wqEbm3FT1QK_6-vL\u0026q=85\u0026s=365e5fb767b72b4fbbb2016860fd92ba","dark":"https://mintcdn.com/formbricks/wqEbm3FT1QK_6-vL/images/logo-dark.svg?fit=max\u0026auto=format\u0026n=wqEbm3FT1QK_6-vL\u0026q=85\u0026s=763690d005584ee5f4b4014615c3b98c"},"favicon":"https://mintcdn.com/formbricks/wqEbm3FT1QK_6-vL/images/favicon.svg?fit=max\u0026auto=format\u0026n=wqEbm3FT1QK_6-vL\u0026q=85\u0026s=01910ab43e3a3acc0aca5471235b90c5","navbar":{"links":[{"href":"/platform/changelog","label":"Release notes"},{"href":"https://github.com/formbricks/formbricks/discussions","label":"Support"}],"primary":{"type":"button","label":"Go to app","href":"https://app.formbricks.com"}},"footer":{"socials":{"github":"https://github.com/formbricks/formbricks","linkedin":"https://linkedin.com/company/formbricks","x":"https://x.com/formbricks"}},"integrations":{"posthog":{"apiKey":"phc_zJO1n3rjHlhqKiJ0gqLDwT4qvfWF1wzHDq2gfl0moQm","apiHost":"https://eu.i.posthog.com"}},"errors":{"404":{"redirect":true}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"formbricks","hasAudioNarration":false,"actualSubdomain":"formbricks","customDomains":["formbricks.com"],"gitSource":{"type":"github","owner":"formbricks","repo":"formbricks","deployBranch":"release/6.2","contentDirectory":"docs","isPrivate":false,"mountPath":"","label":"","_id":"6af9b4d1e79e0e5d7035333b"},"feedback":{"thumbs":true,"issues":true,"edits":true,"agentFeedback":false},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6af9b4d1e79e0e5d70353341","clientVersion":"0.0.4143","searchFilterCounts":[{"language":"default","tag":"Surveys (Ask)","count":99},{"language":"default","tag":"Self Hosting","count":86},{"language":"default","tag":"Surveys","count":76},{"language":"default","tag":"API v2 Reference (Beta)","count":41},{"language":"default","tag":"Upgrade","count":40},{"language":"default","tag":"API v1 Reference","count":36},{"language":"default","tag":"Upgrade by version","count":29},{"language":"default","tag":"Configure","count":28},{"language":"default","tag":"Platform","count":27},{"language":"default","tag":"Development","count":26}]},"assistantConfig":{},"basePath":"/docs","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"self-hosting/upgrade/troubleshooting","slug":"/self-hosting/upgrade/troubleshooting","pageMetadata":{"title":"Troubleshoot an upgrade","description":"Diagnose a blocked migration and choose between repair and restore.","icon":"life-ring","href":"/self-hosting/upgrade/troubleshooting"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Diagnose a blocked migration and choose between repair and restore.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Info,Tab,Tabs,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Info)_missingMdxReference(`Info`,true);if(!Tab)_missingMdxReference(`Tab`,true);if(!Tabs)_missingMdxReference(`Tabs`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Keep maintenance active when an upgrade fails. Record the failed step, source and target images,\nand sanitized error code. Retry only after checking for partial changes and concurrent migration runners.`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Preparation blocked:`}),` use `,_jsx(_components.a,{href:`/self-hosting/upgrade/prepare#results-and-recovery`,children:`preparation results`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Database migration failed:`}),` follow the diagnostic steps below.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Restore required:`}),` use `,_jsx(_components.a,{href:`/self-hosting/operate/backup-restore`,children:`backup and restore`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsxs(_components.strong,{children:[_jsx(_components.code,{children:`StatefulSet.apps \"formbricks-redis-master\" is invalid: spec: Forbidden`}),`:`]}),` see\n`,_jsx(_components.a,{href:`/self-hosting/upgrade/kubernetes#valkey-statefulset-forbidden`,children:`Upgrade fails on the Valkey StatefulSet`}),`.`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`A completed migration is not the final acceptance check. Return to your deployment recipe before\nrestarting writers or reopening traffic.`}),`\n`,_jsx(Heading,{level:`2`,id:`if-a-migration-fails`,children:`If a migration fails`}),`\n`,_jsxs(_components.p,{children:[`From Formbricks 5.3 on, one runner applies every database migration in order: the `,_jsx(_components.code,{children:`formbricks-migrate`}),` service on\nDocker Compose, the `,_jsx(_components.code,{children:`formbricks-migration`}),` Job on Kubernetes (the application pods themselves when the chart sets\n`,_jsx(_components.code,{children:`migration.enabled: false`}),`), or `,_jsx(_components.code,{children:`formbricks-authzed-prepare`}),` during a v5 to v6 upgrade. When a migration fails,\nthe runner stops and no later migration runs. A failed schema migration then blocks every later run until you\nresolve it; a failed data migration is retried on the next run.`]}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`Do not delete volumes, restore a backup or roll the images back before you know which migration failed and\nwhy. Most failures are fixed in place. The output below can contain SQL and data from your instance, so keep\nit out of public issues.`})}),`\n`,_jsx(Heading,{level:`3`,id:`open-a-sql-session`,children:`Open a SQL session`}),`\n`,_jsx(_components.p,{children:`The steps below run SQL as the user that owns the Formbricks tables:`}),`\n`,_jsxs(Tabs,{children:[_jsx(Tab,{title:`One-Click / Docker Compose`,id:`one-click-%2F-docker-compose`,children:_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` compose`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` exec`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` postgres`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` psql`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -U`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` postgres`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` formbricks`})]}),`\n`]})})})}),_jsxs(Tab,{title:`Kubernetes`,id:`kubernetes`,children:[_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`kubectl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` exec`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -it`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -n`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` formbricks`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` formbricks-postgresql-0`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` psql`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -U`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` formbricks`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` formbricks`})]}),`\n`]})})}),_jsx(Info,{children:_jsxs(_components.p,{children:[`If your PostgreSQL pod has a different name, run `,_jsx(_components.code,{children:`kubectl get pods -n formbricks`}),` to find it.`]})})]})]}),`\n`,_jsxs(_components.p,{children:[`With an external or managed PostgreSQL, connect with `,_jsx(_components.code,{children:`psql`}),` as the user in `,_jsx(_components.code,{children:`MIGRATE_DATABASE_URL`}),`, or in\n`,_jsx(_components.code,{children:`DATABASE_URL`}),` if you do not set it. The migrations themselves need a direct or session-pooled connection: a\ntransaction-mode pooler such as PgBouncer can split their session settings across server connections.`]}),`\n`,_jsx(Heading,{level:`3`,id:`1-find-the-failed-migration`,children:`1. Find the failed migration`}),`\n`,_jsxs(_components.p,{children:[`The runner’s output names it. `,_jsx(_components.code,{children:`docker compose run … formbricks-migrate`}),` and the update script print it to your\nterminal; `,_jsx(_components.code,{children:`docker compose logs --tail=200 formbricks-migrate`}),` has it only when the service ran under\n`,_jsx(_components.code,{children:`docker compose up`}),`. On Kubernetes, read `,_jsx(_components.code,{children:`kubectl logs -n formbricks job/formbricks-migration`}),` (by default the\nchart deletes the Job 300 seconds after it fails). A first failure prints `,_jsx(_components.code,{children:`Schema migration batch failed:`}),` with\nevery migration in that batch; the error names the failed one as `,_jsx(_components.code,{children:`Migration name:`}),`, or as `,_jsx(_components.code,{children:`migration_name=\"…\"`}),`\nwhen the real error was hidden. Every run after that stops with `,_jsx(_components.code,{children:`P3009`}),` and names it again. If you have no log,\nincluding with `,_jsx(_components.code,{children:`formbricks-authzed-prepare`}),`, which prints only `,_jsx(_components.code,{children:`upgrade_database_migration_failed`}),` (plus\n`,_jsx(_components.code,{children:`\"reason\":\"timeout\"`}),` when the step ran out its time limit rather than failing), the database always knows:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`sql`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`sql`,children:_jsxs(_components.code,{language:`sql`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`SELECT`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` migration_name, started_at `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`FROM`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"_prisma_migrations\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`WHERE`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` finished_at `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`IS`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` NULL`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` AND`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` rolled_back_at `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`IS`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` NULL`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`If that returns no row but the log says `,_jsx(_components.code,{children:`Data migration … failed`}),`, see `,_jsx(_components.a,{href:`#data-migrations`,children:`Data migrations`}),`\nbelow. If the log just stops without an error, the runner was stopped (Compose stops it after 300 seconds) and\nits last statement may still be running in PostgreSQL: check that first, as step 3 describes.`]}),`\n`,_jsx(Heading,{level:`3`,id:`2-find-the-real-error`,children:`2. Find the real error`}),`\n`,_jsxs(_components.p,{children:[`The runner’s error usually shows it after `,_jsx(_components.code,{children:`Database error:`}),`. If it shows only `,_jsx(_components.code,{children:`current transaction is aborted, commands ignored until end of transaction block`}),`, the migration runs in a transaction of its own and the\n`,_jsx(_components.a,{href:`https://github.com/prisma/prisma/issues/15295`,children:`real error was hidden`}),`. Find it in the PostgreSQL log, on the\n`,_jsx(_components.code,{children:`ERROR`}),` line just before that one:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` compose`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` logs`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` postgres`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` |`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:` grep`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -E`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"ERROR|STATEMENT\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`kubectl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` logs`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -n`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` formbricks`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` formbricks-postgresql-0`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` |`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:` grep`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -E`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"ERROR|STATEMENT\"`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`On a managed service, use your provider’s database log. `,_jsx(_components.code,{children:`canceling statement due to lock timeout`}),` is the most\ncommon cause: another session held a lock on the table the migration changes, for example a long-running query,\na backup, or an old Formbricks pod still running. Stop it, or retry at a quieter time. If the error itself lists\nrecovery steps, as some migrations’ guards do, follow those.`]}),`\n`,_jsx(Heading,{level:`3`,id:`3-check-what-the-migration-left-behind`,children:`3. Check what the migration left behind`}),`\n`,_jsxs(_components.p,{children:[`First make sure nothing is still running it. On Compose, the runner has exited. On Kubernetes, the Job has\nfinished retrying (`,_jsx(_components.code,{children:`kubectl wait -n formbricks --for=condition=Failed job/formbricks-migration --timeout=10m`}),`\nreturns, or the Job is gone). With `,_jsx(_components.code,{children:`migration.enabled: false`}),` the application pods are the runner and retry on\nevery restart, so scale them to 0 (`,_jsx(_components.code,{children:`kubectl scale deploy -n formbricks formbricks --replicas=0`}),`) until step 4. A\nstatement keeps running in PostgreSQL after its runner is stopped, so also list what the database is still\nrunning:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`sql`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`sql`,children:_jsxs(_components.code,{language:`sql`,numberOfLines:`4`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`SELECT`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` pid, `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`now`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`() `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`-`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` query_start `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`AS`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` running_for, `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#DCDCAA`},children:`left`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(query, `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`80`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`AS`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` query,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` pid `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`IN`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`SELECT`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` pid `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`FROM`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` pg_locks `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`WHERE`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` locktype `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'advisory'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` AND`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` objid`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 72707369`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`AS`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` migration_lock`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`FROM`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` pg_stat_activity`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`WHERE`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` datname `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` current_database() `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`AND`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` state`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` IS`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` DISTINCT`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` FROM`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'idle'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` AND`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` pid `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`\u003c>`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` pg_backend_pid();`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`migration_lock`}),` marks a schema migration: Prisma holds that lock while it applies one. Data migrations take no\nsuch lock, so also look for statements on the tables the migration changes. Wait for every migration statement\nto end.`]}),`\n`,_jsx(_components.p,{children:`Then read the failed migration’s file. A released migration never changes, so the copy in your image is the one\nthat ran:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`migration_name`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'\u003cthe name from step 1>'`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` compose`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` run`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --rm`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --no-deps`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --entrypoint`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` cat`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` formbricks-migrate`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"packages/database/dist/migration/${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`migration_name`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}/migration.sql\"`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`It is also on GitHub under any release that ships it, for example\n`,_jsx(_components.code,{children:`https://github.com/formbricks/formbricks/blob/6.0.2/packages/database/migration/\u003cmigration_name>/migration.sql`}),`.`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsxs(_components.strong,{children:[`The runner printed an error, and the whole file is one `,_jsx(_components.code,{children:`BEGIN; … COMMIT;`}),` block, with no statement before\n`,_jsx(_components.code,{children:`BEGIN;`}),` or after `,_jsx(_components.code,{children:`COMMIT;`}),`:`]}),` PostgreSQL rolled the whole file back, so there is nothing to undo. A file that\ncommits a block and then runs more statements, such as `,_jsx(_components.code,{children:`20250911192630_remove_deprecated_fields_and_tables`}),`,\nbelongs under the next case.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Otherwise, including any migration whose runner was stopped instead of printing an error:`}),` the statements\nbefore the failing one may have taken effect, even inside a `,_jsx(_components.code,{children:`BEGIN; … COMMIT;`}),` block. For a stopped runner,\npossibly every statement in the file did: a file Prisma sends as one string runs to its end without a client.\nCheck which did (`,_jsx(_components.code,{children:`\\\\d \"Table\"`}),` for schema changes, a `,_jsx(_components.code,{children:`SELECT`}),` for data) and undo those before you continue. If\nthe new version is already serving, stop it first (`,_jsx(_components.code,{children:`docker compose stop formbricks`}),`, or scale the Deployment to\n0) and keep it stopped until you run the migrations again. Undoing a `,_jsx(_components.code,{children:`DROP`}),` means recreating the object so the\nretry can drop it again; if a change cannot be undone, such as an `,_jsx(_components.code,{children:`UPDATE`}),` whose old values are gone, stop and\nrestore the pre-upgrade backup instead. You need not undo:`,`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`IF NOT EXISTS`}),`, `,_jsx(_components.code,{children:`IF EXISTS`}),` and `,_jsx(_components.code,{children:`CREATE OR REPLACE`}),` statements are safe to repeat, apart from a failed\n`,_jsx(_components.code,{children:`CREATE INDEX CONCURRENTLY`}),`. That leaves an invalid index which `,_jsx(_components.code,{children:`IF NOT EXISTS`}),` then skips: list invalid\nindexes with `,_jsx(_components.code,{children:`SELECT indexrelid::regclass FROM pg_index WHERE NOT indisvalid;`}),` and drop only those the\nmigration’s file creates, with `,_jsx(_components.code,{children:`SET lock_timeout = 0;`}),` and then `,_jsx(_components.code,{children:`DROP INDEX CONCURRENTLY`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`An `,_jsx(_components.code,{children:`UPDATE`}),`, `,_jsx(_components.code,{children:`INSERT`}),` or `,_jsx(_components.code,{children:`DELETE`}),` is safe to repeat only if running it twice changes nothing.`]}),`\n`]}),`\n`]}),`\n`]}),`\n`,_jsx(Heading,{level:`3`,id:`4-mark-it-rolled-back-and-run-the-migrations-again`,children:`4. Mark it rolled back and run the migrations again`}),`\n`,_jsxs(_components.p,{children:[`Once the cause is fixed, mark the failed migration rolled back. This is what\n`,_jsx(_components.code,{children:`prisma migrate resolve --rolled-back`}),` does. It should report `,_jsx(_components.code,{children:`UPDATE 1`}),`; `,_jsx(_components.code,{children:`UPDATE 0`}),` means the name is wrong or\nthe migration is not recorded as failed:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`sql`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`sql`,children:_jsxs(_components.code,{language:`sql`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`UPDATE`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"_prisma_migrations\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` SET`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` rolled_back_at `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` now`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`()`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`WHERE`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` migration_name `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '\u003cmigration_name>'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` AND`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` finished_at `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`IS`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` NULL`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` AND`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` rolled_back_at `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`IS`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` NULL`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`Then run the migrations again:`}),`\n`,_jsxs(Tabs,{children:[_jsxs(Tab,{title:`One-Click / Docker Compose`,id:`one-click-%2F-docker-compose-2`,children:[_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` compose`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` run`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --rm`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --no-deps`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` formbricks-migrate`})]}),`\n`]})})}),_jsx(_components.p,{children:`The service stops the runner after 300 seconds. If a migration needs longer, run it without that limit:`}),_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` compose`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` run`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --rm`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --no-deps`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` formbricks-migrate`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"node packages/database/dist/scripts/apply-migrations.js\"`})]}),`\n`]})})}),_jsxs(_components.p,{children:[`During a v5 to v6 upgrade, re-run `,_jsx(_components.code,{children:`formbricks-authzed-prepare`}),` as the\n`,_jsx(_components.a,{href:`/self-hosting/upgrade/versions/6.0`,children:`v6 maintenance upgrade guide`}),` describes instead.`]})]}),_jsxs(Tab,{title:`Kubernetes`,id:`kubernetes-2`,children:[_jsxs(_components.p,{children:[`Delete the failed Job, then run the same `,_jsx(_components.code,{children:`helm upgrade`}),` (or Argo CD sync) again. Helm does not re-run a Job\nthat still exists, and refuses to change one (`,_jsx(_components.code,{children:`field is immutable`}),`):`]}),_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`kubectl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` delete`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` job`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -n`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` formbricks`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` formbricks-migration`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --ignore-not-found`})]}),`\n`]})})}),_jsxs(_components.p,{children:[`With `,_jsx(_components.code,{children:`migration.enabled: false`}),`, scale the Deployment back up instead; its pods run the migrations on start.`]}),_jsxs(_components.p,{children:[`Otherwise, if you scaled the Deployment to 0 in step 3, scale it back up once the Job succeeds\n(`,_jsx(_components.code,{children:`kubectl scale deploy -n formbricks formbricks --replicas=\u003cyour count>`}),`). `,_jsx(_components.code,{children:`helm upgrade`}),` restores the count\nonly when `,_jsx(_components.code,{children:`autoscaling.enabled`}),` is false and `,_jsx(_components.code,{children:`deployment.replicas`}),` is set, and an autoscaler does not scale up\nfrom 0.`]}),_jsxs(_components.p,{children:[`During a v5 to v6 upgrade, delete and re-create the `,_jsx(_components.code,{children:`formbricks-v6-prepare`}),` Job as the\n`,_jsx(_components.a,{href:`/self-hosting/upgrade/versions/6.0`,children:`v6 maintenance upgrade guide`}),` describes instead.`]})]})]}),`\n`,_jsx(Heading,{level:`3`,id:`data-migrations`,children:`Data migrations`}),`\n`,_jsxs(_components.p,{children:[`Most data migrations run in a transaction of their own and leave nothing behind when they fail; the large ones\ncommit in batches and are written to resume where they stopped. Either way the runner records the failure and\nretries the migration on the next run: fix the cause and run the migrations again. The exception is\n`,_jsx(_components.code,{children:`Migration is pending. Please resolve the issue manually.`}),`, left by an interrupted run of a version before 5.3.\nMake sure nothing is still running it (step 3), then mark it failed so the next run retries it:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`sql`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`sql`,children:_jsxs(_components.code,{language:`sql`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`SELECT`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` name`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`status`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, started_at `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`FROM`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"DataMigration\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` WHERE`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` status`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` \u003c>`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'applied'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`UPDATE`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"DataMigration\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` SET`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` status`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'failed'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` WHERE`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` name`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '\u003cname>'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` AND`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` status`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'pending'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`]})})})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Troubleshoot an upgrade","description":"Diagnose a blocked migration and choose between repair and restore.","icon":"life-ring","href":"/self-hosting/upgrade/troubleshooting"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"If a migration fails","slug":"if-a-migration-fails","depth":2,"children":[{"title":"Open a SQL session","slug":"open-a-sql-session","depth":3,"children":[]},{"title":"1. Find the failed migration","slug":"1-find-the-failed-migration","depth":3,"children":[]},{"title":"2. Find the real error","slug":"2-find-the-real-error","depth":3,"children":[]},{"title":"3. Check what the migration left behind","slug":"3-check-what-the-migration-left-behind","depth":3,"children":[]},{"title":"4. Mark it rolled back and run the migrations again","slug":"4-mark-it-rolled-back-and-run-the-migrations-again","depth":3,"children":[]},{"title":"Data migrations","slug":"data-migrations","depth":3,"children":[]}]}],"codeExamples":{}},"jsLinks":["/docs/_mintlify/custom/formbricks/7af300e0bdc69f45/formbricks.js"],"subdomain":"formbricks","siteName":"Documentation - Formbricks","title":"Troubleshoot an upgrade - Documentation - Formbricks","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-15T13:34:29.423Z","originalFileLocation":"self-hosting/upgrade/troubleshooting.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Diagnose a blocked migration and choose between repair and restore.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Documentation - Formbricks\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/formbricks/GlZ4IqkvkQlhFmAc/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/docs/mintlify-assets/_mintlify/favicons/formbricks/GlZ4IqkvkQlhFmAc/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/formbricks/GlZ4IqkvkQlhFmAc/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/formbricks/GlZ4IqkvkQlhFmAc/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/formbricks/GlZ4IqkvkQlhFmAc/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/formbricks/GlZ4IqkvkQlhFmAc/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/formbricks/GlZ4IqkvkQlhFmAc/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/formbricks/GlZ4IqkvkQlhFmAc/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/formbricks/GlZ4IqkvkQlhFmAc/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Troubleshoot an upgrade - Documentation - Formbricks\">\u003cmeta data-mint-head property=\"og:description\" content=\"Diagnose a blocked migration and choose between repair and restore.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Documentation - Formbricks\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://formbricks.com/docs/self-hosting/upgrade/troubleshooting\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://formbricks.mintlify.site/docs/_mintlify/api/og/v2?division=Reference\u0026amp;title=Troubleshoot+an+upgrade\u0026amp;description=Diagnose+a+blocked+migration+and+choose+between+repair+and+restore.\u0026amp;theme=ad31bfbf4dbc0f4212be5b08\u0026amp;signature=66fe5c9dc14cf5ac9d5dc45fbaaa4575f10a6ecd931e50eaaa627f3ba8342282\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Troubleshoot an upgrade - Documentation - Formbricks\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Diagnose a blocked migration and choose between repair and restore.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://formbricks.mintlify.site/docs/_mintlify/api/og/v2?division=Reference\u0026amp;title=Troubleshoot+an+upgrade\u0026amp;description=Diagnose+a+blocked+migration+and+choose+between+repair+and+restore.\u0026amp;theme=ad31bfbf4dbc0f4212be5b08\u0026amp;signature=66fe5c9dc14cf5ac9d5dc45fbaaa4575f10a6ecd931e50eaaa627f3ba8342282\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/docs/mintlify-assets/_mintlify/favicons/formbricks/GlZ4IqkvkQlhFmAc/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Documentation - Formbricks\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#00C4B8\">\u003clink data-mint-head rel=\"canonical\" href=\"https://formbricks.com/docs/self-hosting/upgrade/troubleshooting\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/docs/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/self-hosting/upgrade/troubleshooting.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://formbricks.com/#organization\",\"name\":\"Documentation - Formbricks\",\"url\":\"https://formbricks.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/formbricks/wqEbm3FT1QK_6-vL/images/logo-light.svg?fit=max\u0026auto=format\u0026n=wqEbm3FT1QK_6-vL\u0026q=85\u0026s=365e5fb767b72b4fbbb2016860fd92ba\"}},{\"@type\":\"WebSite\",\"@id\":\"https://formbricks.com/docs#website\",\"name\":\"Documentation - Formbricks\",\"url\":\"https://formbricks.com/docs\",\"publisher\":{\"@id\":\"https://formbricks.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://formbricks.com/docs/self-hosting/upgrade/troubleshooting#webpage\",\"url\":\"https://formbricks.com/docs/self-hosting/upgrade/troubleshooting\",\"name\":\"Troubleshoot an upgrade\",\"description\":\"Diagnose a blocked migration and choose between repair and restore.\",\"dateModified\":\"2026-11-15T13:34:29.423Z\",\"isPartOf\":{\"@id\":\"https://formbricks.com/docs#website\"},\"breadcrumb\":{\"@id\":\"https://formbricks.com/docs/self-hosting/upgrade/troubleshooting#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://formbricks.com/docs/self-hosting/upgrade/troubleshooting#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Upgrade\",\"item\":\"https://formbricks.com/docs/self-hosting/advanced/upgrade\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Reference\",\"item\":\"https://formbricks.com/docs/self-hosting/upgrade/configuration\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Troubleshoot an upgrade\",\"item\":\"https://formbricks.com/docs/self-hosting/upgrade/troubleshooting\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://formbricks.com/docs/self-hosting/upgrade/troubleshooting#article\",\"headline\":\"Troubleshoot an upgrade\",\"name\":\"Troubleshoot an upgrade\",\"description\":\"Diagnose a blocked migration and choose between repair and restore.\",\"url\":\"https://formbricks.com/docs/self-hosting/upgrade/troubleshooting\",\"mainEntityOfPage\":{\"@id\":\"https://formbricks.com/docs/self-hosting/upgrade/troubleshooting#webpage\"},\"dateModified\":\"2026-11-15T13:34:29.423Z\",\"publisher\":{\"@id\":\"https://formbricks.com/#organization\"},\"isPartOf\":{\"@id\":\"https://formbricks.com/docs#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Documentation - Formbricks\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Documentation - Formbricks\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/docs/self-hosting/upgrade/troubleshooting.md","siteName":"Documentation - Formbricks","nav":{"global":null,"tabs":[{"tab":"Platform","pages":[{"title":"Platform","href":"/platform/introduction"}]},{"tab":"Surveys (Ask)","pages":[{"title":"Surveys (Ask)","href":"/surveys/overview"}]},{"tab":"Unify Feedback (Analyze)","pages":[{"title":"Unify Feedback (Analyze)","href":"/unify-feedback/overview"}]},{"tab":"Workflows (Act)","pages":[{"title":"Workflows (Act)","href":"/workflows/overview"}]},{"tab":"Self Hosting","groups":[{"group":"Overview","pages":[{"title":"Self-Hosting","icon":"server","href":"/self-hosting/overview"},{"title":"Deployment components","icon":"cubes","href":"/self-hosting/deployment-components"}]},{"group":"Install","pages":[{"title":"Kubernetes Deployment","icon":"circle-nodes","href":"/self-hosting/setup/kubernetes"},{"title":"One-Click Setup","icon":"rocket","href":"/self-hosting/setup/one-click"},{"title":"Docker Setup","icon":"docker","href":"/self-hosting/setup/docker"}]},{"group":"Upgrade","pages":[{"title":"Upgrade Formbricks","icon":"arrow-up-right-dots","href":"/self-hosting/advanced/upgrade"},{"title":"Upgrade paths","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/paths"},{"group":"Runbooks","pages":[{"title":"Upgrade Kubernetes","icon":"dharmachakra","href":"/self-hosting/upgrade/kubernetes"},{"title":"Upgrade Docker Compose","icon":"docker","href":"/self-hosting/upgrade/docker"},{"title":"Upgrade one-click","icon":"rocket","href":"/self-hosting/upgrade/one-click"},{"title":"Upgrade within 4.x or to 5.x","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/legacy"}]},{"group":"Upgrade by version","pages":[{"title":"All versions","icon":"arrow-up-right-dots","href":"/self-hosting/advanced/migration"},{"group":"6.x","pages":[{"title":"6.0: Upgrade guide","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/6.0"},{"title":"6.1: Upgrade guide","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/6.1"},{"title":"6.1: Runtime changes","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/6.1-runtime"},{"title":"6.1.0: Single-use links","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/6.1-single-use-links"},{"title":"6.1.0: Survey visibility","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/6.1-visibility"},{"title":"6.2: Upgrade guide","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/6.2"},{"title":"6.2: Dashboard viewer role","icon":"chart-line","href":"/self-hosting/upgrade/versions/dashboard-viewer"},{"title":"6.2: Charts and dashboards API","icon":"chart-column","href":"/self-hosting/upgrade/versions/charts-dashboards"},{"title":"6.2: Question codes and the published lock","icon":"lock","href":"/self-hosting/upgrade/versions/question-codes"},{"title":"6.2: Attachment exports and new job queues","icon":"file-zipper","href":"/self-hosting/upgrade/versions/attachment-exports"},{"title":"6.2: Valkey 9 upgrade","icon":"database","href":"/self-hosting/upgrade/versions/valkey-9"},{"title":"6.2: Cube memory and PostgreSQL shared memory","icon":"memory","href":"/self-hosting/upgrade/versions/cube-memory"},{"title":"6.2: Helm connects Cube and the SpiceDB bootstrap to the bundled database","icon":"database","href":"/self-hosting/upgrade/versions/helm-bundled-database"}]},{"group":"5.x","pages":[{"title":"5.0: Upgrade guide","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/5.0"},{"title":"5.1: Upgrade guide","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/5.1"},{"title":"5.2: Upgrade guide","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/5.2"},{"title":"5.3: Upgrade guide","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/5.3"},{"title":"5.4: Upgrade guide","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/5.4"},{"title":"5.4.0: Database preparation","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/5.4-database"},{"title":"5.4: Authentication changes","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/5.4-authentication"},{"title":"5.4.0: Feedback API permissions","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/5.4-api-permissions"},{"title":"5.4: Dependency changes","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/5.4-runtime"}]},{"group":"4.x","pages":[{"title":"4.x: Other upgrade notes","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/4.x"},{"title":"4.0: Upgrade guide","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/4.0"},{"title":"4.7: Upgrade guide","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/4.7"}]},{"group":"Patch releases","pages":[{"title":"5.4.8 / 6.0.5 / 6.1.2: Security updates","icon":"shield-halved","href":"/self-hosting/upgrade/versions/2026-10-27-patches"},{"title":"5.4.7 / 6.0.4 / 6.1.1: Security updates","icon":"shield-halved","href":"/self-hosting/upgrade/versions/2026-10-security-patches"},{"title":"5.4.5 / 6.0.2: Cube image migration","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/versions/cube"}]}]},{"group":"Reference","pages":[{"title":"Prepare the target configuration","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/configuration"},{"title":"Prepare permissions","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/prepare"},{"title":"Rehearse an upgrade","icon":"arrow-up-right-dots","href":"/self-hosting/upgrade/rehearse"},{"title":"One-click updater behavior","description":"What a release-matched updater changes and what you must prepare yourself.","icon":"terminal","href":"/self-hosting/upgrade/one-click-details"},{"title":"Troubleshoot an upgrade","icon":"life-ring","href":"/self-hosting/upgrade/troubleshooting"}]}]},{"group":"Configure","pages":[{"title":"Configuration","sidebarTitle":"Overview","description":"Everything you can configure on a self-hosted Formbricks instance, and where each setting lives.","icon":"sliders","href":"/self-hosting/configuration"},{"title":"Custom SSL Certificate","icon":"lock","href":"/self-hosting/configuration/custom-ssl"},{"title":"Environment Variables","icon":"code","href":"/self-hosting/configuration/environment-variables"},{"title":"SMTP Configuration","icon":"envelope","href":"/self-hosting/configuration/smtp"},{"title":"File Uploads Configuration","icon":"upload","href":"/self-hosting/configuration/file-uploads"},{"title":"Domain Configuration","icon":"globe","href":"/self-hosting/configuration/domain-configuration"},{"title":"CDN","icon":"globe","href":"/self-hosting/configuration/cdn"},{"title":"Custom Subpath","icon":"link","href":"/self-hosting/configuration/custom-subpath"},{"title":"AI Features","icon":"sparkles","sidebarTitle":"AI Features","href":"/self-hosting/configuration/ai-features"},{"title":"AI timeouts","icon":"clock","href":"/self-hosting/configuration/ai-timeouts"},{"title":"Rate Limiting","icon":"timer","href":"/self-hosting/configuration/rate-limiting"},{"title":"Envoy Gateway","icon":"route","href":"/self-hosting/configuration/envoy"},{"group":"Auth \u0026 SSO","icon":"lock","pages":[{"title":"Authentication Behavior","icon":"user","href":"/self-hosting/auth-behavior"},{"title":"Open ID Connect","icon":"key","href":"/self-hosting/configuration/auth-sso/open-id-connect"},{"title":"Keycloak OIDC","icon":"key-skeleton-left-right","href":"/self-hosting/configuration/auth-sso/keycloak-oidc"},{"title":"Okta OIDC","icon":"fingerprint","href":"/self-hosting/configuration/auth-sso/okta-oidc"},{"title":"Azure AD OAuth","icon":"microsoft","href":"/self-hosting/configuration/auth-sso/azure-ad-oauth"},{"title":"Google OAuth","icon":"google","href":"/self-hosting/configuration/auth-sso/google-oauth"},{"title":"SAML SSO","icon":"user-shield","href":"/self-hosting/configuration/auth-sso/saml-sso"},{"title":"SAML with Identity Providers","icon":"building-lock","href":"/self-hosting/configuration/auth-sso/setup-saml-with-identity-providers"}]},{"group":"Integrations","icon":"bridge","pages":[{"title":"Third-party Integrations (On Premise)","sidebarTitle":"Overview","icon":"bridge","href":"/self-hosting/configuration/integrations"},{"title":"Airtable (On Premise)","icon":"table","href":"/self-hosting/configuration/integrations/airtable"},{"title":"Google Sheets (On Premise)","icon":"file-spreadsheet","href":"/self-hosting/configuration/integrations/google-sheets"},{"title":"Notion (On Premise)","icon":"book","href":"/self-hosting/configuration/integrations/notion"},{"title":"Slack (On Premise)","icon":"slack","href":"/self-hosting/configuration/integrations/slack"}]},{"title":"Deploy optional AI services","icon":"sparkles","href":"/self-hosting/configuration/ai-deployment"},{"title":"Run RustFS with Docker","icon":"database","href":"/self-hosting/configuration/docker-storage"},{"title":"External PostgreSQL for SpiceDB","icon":"database","href":"/self-hosting/configuration/spicedb-external-postgres"}]},{"group":"Operate","pages":[{"title":"Components and ownership","icon":"boxes-stacked","href":"/self-hosting/operate/components"},{"title":"Deployment check","icon":"clipboard-check","href":"/self-hosting/setup/deployment-check"},{"title":"Architecture and scaling","icon":"circle-nodes","href":"/self-hosting/setup/cluster-setup"},{"title":"Monitoring","icon":"magnifying-glass-chart","href":"/self-hosting/setup/monitoring"},{"title":"Job Runner","icon":"gears","href":"/self-hosting/configuration/job-runner"},{"title":"SpiceDB Authorization Operations","icon":"shield-halved","href":"/self-hosting/configuration/authzed-operations"},{"title":"Backup and restore","icon":"database","href":"/self-hosting/operate/backup-restore"},{"title":"Migrating Surveys","icon":"right-left","href":"/self-hosting/advanced/migrating-surveys"},{"title":"Migrating Survey Responses","icon":"database","href":"/self-hosting/advanced/migrating-survey-responses"}]},{"group":"Licensing and support","pages":[{"title":"License","icon":"file-certificate","href":"/self-hosting/advanced/license"},{"title":"License Activation","icon":"key","href":"/self-hosting/advanced/license-activation"},{"title":"Audit Logging","sidebarTitle":"Audit Logging","icon":"file-shield","href":"/self-hosting/advanced/enterprise-features/audit-logging"},{"title":"Release and Maintenance Policy","icon":"calendar-check","href":"/self-hosting/advanced/release-maintenance-policy"}]}]},{"tab":"Development","pages":[{"title":"Development","href":"/development/overview"}]},{"tab":"Integrate","pages":[{"title":"Integrate","href":"/integrate/overview"}]},{"tab":"API v1 Reference","pages":[{"title":"API v1 Reference","href":"/api-reference/rest-api"}]},{"tab":"API v2 Reference (Beta)","pages":[{"title":"API v2 Reference (Beta)","href":"/api-v2-reference/introduction"}]},{"tab":"API v3 Reference (Private Beta)","hidden":true,"pages":[{"title":"API v3 Reference (Private Beta)","href":"/api-v3-reference/introduction"}]}]},"basePath":"","title":"Troubleshoot an upgrade - Documentation - Formbricks","buildId":"dpl_Aw98ji4XvBsgtZwL1VrkUF9ehFqz","deploymentId":"dpl_Aw98ji4XvBsgtZwL1VrkUF9ehFqz","dynamics":[],"chunks":[]}