mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-20 14:34:25 +00:00
8395d4326e
<!-- Please inform yourself about the contribution guidelines on submitting a PR here: https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr. Take note of how PR/commit titles should be written and replace the template texts in the sections below. Don't remove any of the sections. It is important that the commit history clearly shows what is changed and why. Important: By submitting a contribution you agree to the terms from our Licensing Policy as described here: https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions. --> # Which Problems Are Solved - Operators upgrading from ZITADEL v3 to v4 lacked a clear, docs-backed upgrade path covering web keys (A-10017), Login V1 vs Login V2 expectations, and post-upgrade options. - There was no standalone guide for adopting Login V2 after already running on v4. - Related ops/docs pages did not consistently point readers to the upgrade and Login V2 adoption material. - Kubernetes/Helm operators upgrading to a chart that ships ZITADEL v4 had no ops-page section linking the advisory, upgrade guide, optional Login V2 deferral (`login.enabled: false`), and chart README upgrade notes. # How the Problems Are Solved - Adds technical advisory **A-10017** documenting OIDC web key staging requirements before upgrading to v4. - Adds an **upgrade-v3-to-v4** guide with the recommended upgrade path (Login V1 remains supported; Login V2 is optional at upgrade time). - Adds a **v4-only adopt-login-v2** guide for teams adopting Login V2 later, with steps and caveats separate from the version upgrade. - Adds an **Upgrading to ZITADEL v4** subsection under `self-hosting/deploy/kubernetes/operations.mdx` that links to A-10017, the upgrade guide, Adopt Login V2, notes `login.enabled: false` when not adopting Login V2 yet, and points to the [Helm chart README](https://github.com/zitadel/zitadel-charts/blob/main/charts/zitadel/README.md) for chart-specific breaking changes. # Additional Changes - Registers new docs in the sidebar and wires Related / cross-links from upgrade and ops pages so the advisory and guides are discoverable together. - Aligns language so upgrade vs. Login V2 adoption are clearly separated concerns. - Light cross-link updates on troubleshooting / updating-scaling / login-client pages where related. # Additional Context - Related: A-10017 (web keys advisory) - Docs paths introduced/updated: - `apps/docs/content/support/advisory/a10017.mdx` - `apps/docs/content/self-hosting/manage/upgrade-v3-to-v4.mdx` - `apps/docs/content/self-hosting/manage/adopt-login-v2.mdx` - `apps/docs/content/self-hosting/deploy/kubernetes/operations.mdx` (new "Upgrading to ZITADEL v4" section) - Sidebar and Related / cross-links - Companion Helm chart README PR: https://github.com/zitadel/zitadel-charts/pull/608 --------- Co-authored-by: Cursor <[email protected]>
52 lines
3.6 KiB
Plaintext
52 lines
3.6 KiB
Plaintext
---
|
|
title: Troubleshoot ZITADEL
|
|
description: "Resolve common ZITADEL self-hosting issues, including instance not found and upstream header errors during deployment troubleshooting"
|
|
---
|
|
|
|
import InstanceNotFound from "../../../self-hosting/deploy/troubleshooting/_instance_not_found.mdx";
|
|
|
|
import UpstreamHeader from "../../../self-hosting/deploy/troubleshooting/_upstream_header.mdx"
|
|
|
|
## Instance not found
|
|
|
|
<InstanceNotFound components={props.components} />
|
|
|
|
## upstream sent too big header while reading response header from upstream
|
|
|
|
<UpstreamHeader components={props.components} />
|
|
|
|
## Container restarts after upgrading to a new version
|
|
|
|
When you upgrade ZITADEL to a newer version, the setup phase runs database migrations automatically.
|
|
|
|
**Which command to use for upgrades:**
|
|
|
|
- `start-from-init` (used in the quickstart) runs **init → setup → start** in sequence. The init phase is only needed once ever (for a fresh database), but it is safe to re-run because it skips resources that already exist. Use `start-from-init` only for the quickstart or when you're sure the database needs initialising from scratch.
|
|
- **For upgrades on existing installations**, prefer `start-from-setup` (runs setup → start) or run `zitadel setup` followed by `zitadel start` as separate steps. This avoids running the init phase unnecessarily and is the recommended production approach. See [Update and Scale ZITADEL](/self-hosting/manage/updating_scaling) for details.
|
|
|
|
If the container exits with code 1 and the logs show a database migration error, check the following:
|
|
|
|
- Make sure the PostgreSQL version meets the [requirements](/self-hosting/manage/database). PostgreSQL 18 support requires ZITADEL v4.11.0 or later.
|
|
- Log messages like `role "zitadel" already exists` or `database "zitadel" already exists` during `start-from-init` re-runs are **expected and harmless** — the init phase skips those steps.
|
|
- If the container still fails after a version upgrade, check whether the version you are upgrading to lists any known migration issues in the [release notes](https://github.com/zitadel/zitadel/releases).
|
|
|
|
## Instance settings (FIRSTINSTANCE / DEFAULTINSTANCE) not taking effect after restart
|
|
|
|
Environment variables prefixed with `ZITADEL_FIRSTINSTANCE_` and `ZITADEL_DEFAULTINSTANCE_` are only applied during the **initial creation** of a ZITADEL instance.
|
|
Changing these variables and restarting the container will not update an already-existing instance.
|
|
|
|
To change instance-level settings on a running installation:
|
|
- Use the [Admin Console](https://your-domain/ui/console/instance) to update settings interactively.
|
|
- Use the Admin API to automate changes.
|
|
|
|
**Login V2**: Starting with ZITADEL v4, the Login V2 UI is enabled by default for new installations.
|
|
Existing instances keep Login V1 until you opt in. To adopt Login V2 on an existing v4 installation, see [Adopt Login V2](/self-hosting/manage/adopt-login-v2).
|
|
|
|
## ZITADEL service becomes unhealthy without visible error messages
|
|
|
|
If the `zitadel` container shows as `unhealthy` but the log output does not reveal an obvious error:
|
|
|
|
1. Increase log verbosity by setting `ZITADEL_LOG_LEVEL: debug` and `ZITADEL_LOGSTORE_ACCESS_STDOUT_ENABLED: true`.
|
|
2. Check that the healthcheck command can reach ZITADEL. The built-in `zitadel ready` command uses HTTP when `ZITADEL_TLS_ENABLED=false` and HTTPS otherwise. Ensure that this variable matches your TLS settings.
|
|
3. If ZITADEL is running behind a reverse proxy, make sure the proxy forwards traffic correctly before the first healthcheck succeeds. See [Run and configure a reverse proxy](/self-hosting/manage/reverseproxy/reverse_proxy).
|