Files
ZitPlane/docs/TROUBLESHOOTING.md
T

6.1 KiB

ZitPlane — Troubleshooting and safe diagnostics

Scope: Only describe issues the current source or recorded phase evidence supports. Run #86 verified an isolated disposable backend, but no developer-PC environment or production deployment has been verified.

Symptom Known possible cause Safe next action
docker command not found Docker CLI/Desktop was missing on the previously inspected Windows host during P02 Install supported Docker Engine/Desktop and run only in a local disposable environment; do not treat a source manifest as runtime acceptance
docker compose config / up fails Local machine Docker/config differences or occupied port may differ from validated CI stack Gitea Run #86 verified isolated portless CI Compose; check environment-specific logs with secrets redacted; do not confuse its portless override with P02 local loopback Compose
Admin Console login fails First-instance bootstrap, Login V2 container/PAT, auth proxy or credentials not validated Verify local health, first-init logs and policy in a secret-safe environment; do not reinitialize volumes casually
Account Portal shows no page App dependencies are not installed; no Account Portal image, runtime or domain is configured Complete reviewed lockfile/build/CI and explicit integration phase before troubleshooting live UI
Redirect/callback error after future login OIDC issuer/callback URL, client type/secret, proxy headers, PKCE/state or allowed redirect may mismatch Compare exact configured origins and registered callback; never weaken checks or wildcard redirects
Unauthorized on /api/account/me Designed result for absent/expired user identity Authenticate through ZITADEL; if unexpected in a future runtime, inspect token expiry and session trace securely
Profile Save button missing Portal source has read-only fields only Use permitted ZITADEL self-service (if configured) or wait for an approved custom edit feature
MFA/passkey settings not editable in portal Portal only shows informational cards and a link Use the identity provider's policy-supported controls; do not paste secrets into support messages
Sign-out seems to leave other applications signed in Portal signOut is portal-local, not federated logout Close respective sessions via app/identity provider; global logout requires a future dedicated implementation
auth.vib.tools / account.vib.tools unavailable They are planned hostnames, no production deployment configured Do not assume DNS/SSL/Coolify service exists; await P07
Login V2 custom source appears unchanged when starting P02 Compose P02 Compose uses prebuilt official Login UI, not P03 imported code Later P05 must build and wire custom image after CI and explicit approval

How to report a safe issue

Include environment (local disposable vs CI vs production), exact phase/commit, which page/action, a redacted error and reproduction conditions. Never publish .env, client secret, passwords, access tokens, cookies, private keys or user data. Link to relevant phase note; record the fix and updated user guidance together.

P05-CI-02 verification and error boundaries

  • Prior Account Portal TS2345 at src/auth.ts(14,61) in Gitea Run #81 was fixed by verified JWT subject narrowing; Gitea Run #83 Account Portal typecheck/build PASS.
  • Previous Alpine backend checkout missed Git; Run #83 verified the fix. Run #83 also exposed an occupied shared-runner host TCP 8080. Run #86 verified the portless CI Compose overlay: all four services ready, disposable Postgres restart persistence, ZITADEL ready/OIDC discovery/JWKS and complete CI-only cleanup PASS. This does not prove the separate P02 local PC Compose or real user login.
  • A green HIGH/CRITICAL advisory audit gate still allows Moderate findings. P05-SEC-01 updates only approved Next.js/OTel dependency manifests and lockfiles and adds an independent zero Moderate/High/Critical acceptance gate. Potential glob/minimatch transitive major-version issues remain open until a real registry CI audit proves otherwise; no suppressions or forced compatibility-breaking overrides.
  • CI negative access tests do not simulate real login; actual OIDC app registration/authorized login/MFA must receive separate approval.

Known limitations

Account Portal and Login V2 build CI passed in Run #83, disposable backend acceptance passed in Run #86, and dependency lockfiles/workflows exist. Real authenticated OIDC callback/positive session, MFA/passkey, Admin Console human login, production Coolify/TLS/backup and production support remain UNVERIFIED. Preserve the Scope Lock in notes/ and ZITADEL security boundaries.

P05-SEC-01 exact security-blocker troubleshooting

Gitea Run #87 produced 3 PASS and 1 FAIL. The FAILED security_login job is a deliberate fail-closed Moderate threshold: GHSA-3g3m-2fjr-6pw4 in glob (fix >=14.0.2) and GHSA-g3hv-75wg-m249 in minimatch (fix >=11.0.1). Account npm audit returned 0. Login's earlier Next.js/OTel advisories no longer reproduce, its frozen build and 1219 tests PASS, and High/Critical remain 0. Do not turn off auditing, ignore Moderate reports, modify protected auth code or force incompatible package majors. A separate P05-SEC-02 exact Scope Lock must allow controlled PNPM workspace overrides or verified compatible parent upgrades; only a new focused CI run can close security acceptance.

P05-SEC-02 — scoped major transitive override troubleshooting

If a frozen Login install, Nx build or unit suite fails after this patch, verify the seven exact parent@version>dependency selectors in auth/ui/v2/pnpm-workspace.yaml and the matching pnpm-lock.yaml snapshots; compare with notes/P05-SEC-02.md. glob@14 and minimatch@11 are semver-major transitive substitutions, so historical parents expecting v10 APIs may need a separately approved compatible parent upgrade. Do not apply global overrides, blanket pnpm audit --fix, disable the strict zero-Moderate gate, or edit protected Login authentication code. Full security acceptance requires current CI frozen install/build/Vitest and registry audit, not just a clean lockfile.