Are there any guides / docs on upgrading from v2 to v4? Do i have to upgrade to v3 first?

I saw the docs mention that look at the release nodes to see whats changed but i was wondering if there were any definitive guides that serve as sort of checklist when upgrading from v2 -> v3 and v3 -> v4 for self-hosted zitadel.

Ask Inkeep•10/3/25, 3:10 PM

Hi @Shardool, I'm an AI assistant for ZITADEL. While a team member reviews this question, I'll see if I can find relevant sources for your question.

Ask Inkeep•10/3/25, 3:10 PM

Answer

Based on the available sources, there isn't a comprehensive upgrade guide that specifically covers v2 → v3 → v4 migrations as a checklist. However, I can provide some key information about these upgrades:

Critical Requirements for v3

For upgrading to ZITADEL v3, you must migrate from CockroachDB to PostgreSQL if you're currently using CockroachDB (1) . ZITADEL v3 requires PostgreSQL as a database and will not start if CockroachDB is configured . You can use the mirror command to migrate data to PostgreSQL before deploying v3 (2) (1) .

General Upgrade Process

From the community discussions, the general upgrade process involves questions-help-bugsUpgrade Zitadel from v2.37.3 to latest :

Backup your database
Read technical advisories for breaking changes
For versions ≥ 2.44.0, use the --init-projections--init-projections flag if you want migration to finish before runtime starts
Run zitadel setupzitadel setup between version upgrades (4)
Start the normal ZITADEL container when setup shows "setup successful" questions-help-bugsUpgrade Zitadel from v2.37.3 to latest

## Potential Issues

Community members have reported various issues during major version upgrades, including migration errors (5) and functionality problems after upgrading to v4 (4) . Some users have needed to rollback and retry upgrades .

I wasn't able to find a direct answer for comprehensive upgrade guides, here are some relevant sources:

[Technical Adv

Ask Inkeep•10/3/25, 3:10 PM

isory 10015](https://zitadel.com/docs/support/advisory/a10015) : Details the CockroachDB to PostgreSQL migration requirement for v3

Mirror data from cockroach to postgres : Provides the migration process for database changes

For the most current and complete upgrade procedures, you may want to click the "Ask for help" button to have a team member provide specific guidance for your version upgrade path.

Ask Inkeep•10/3/25, 3:10 PM

To learn more, see the sources I considered:

[1] Technical Advisory 10015
[2] Mirror data from cockroach to postgres
questions-help-bugsUpgrade Zitadel from v2.37.3 to latest
[4] Discord message from @larzous on 2025-08-04
[5] [Bug]: Upgrade to v2.71.5 fails with migration error ("idp_templates6_ldap2" already exists)

Ask Inkeep•10/3/25, 3:10 PM

Feel free to tag @Ask Inkeep with additional questions.