Troubleshooting¶

Record the time, executor / tracker name, run ID, and error category first. Remove tokens, passwords, Webhook URLs, kubeconfigs, and sensitive snapshot fields before sharing logs.

Read the first-install bootstrap password from startup logs; existing installations do not generate another one. For forgotten or blocked legacy default passwords, use Administrator recovery. Do not delete user tables or key files to force initialization.

OIDC failure¶

redirect_uri_mismatch: compare the IdP callback with {BASE URL}/auth/oidc/{slug}/callback exactly, including HTTPS, sub-path, and Slug.
Provider configured but login unavailable: confirm the administrator binding was completed, not just provider creation.
Binding or callback failure: check HTTPS, browser cookies, system time, and IdP signing configuration. Retain the error category, not the full authorization URL.

Start a fresh login flow after fixing configuration; do not replay old callbacks. See Administrator and OIDC.

UI works but API / assets return 404¶

Compare the root and sub-path examples: preserve paths at the root, strip a sub-path prefix exactly once. Match BASE URL to the external address and ensure APIs return JSON rather than an SPA page. Reload from the external URL after changes.

Missing or unexpected versions¶

Check in order: source address and credentials → upstream rate limits / request failures → Release and Tag fallback → channels, include and exclude patterns → fetch depth → publish-time / SemVer sorting.

Run a manual check for one source and inspect the returned versions. Rules match tags, not release bodies. See Version rules.

New version but no update¶

Check executor/runtime enabled states, the specific source and release-channel binding, manual mode, maintenance windows, and whether the target is already current. Inspect skip reasons and active runs in execution history, not just the tracker's displayed version.

See Execution policies.

Runtime connection or discovery failure¶

Target	Check first
Docker / Podman	`unix://` or `tcp://` prefix, Socket mount, process permissions, listening service
TLS connection	CA trust, certificate expiry, hostname; do not disable verification
Kubernetes	Context, valid credentials, namespace permissions, ServiceAccount
Portainer	API key, Endpoint ID, platform availability, stack type
SSH	Host key fingerprint changes, authentication, jump host, remote Compose tool and file permissions

See Credentials and runtimes for configuration.

Health-check failure¶

Confirm the target supports the selected pipeline, then check reachability from the instance. HTTP private-address or redirect rejection is a security policy, not a DNS failure. Adjust grace periods and probe windows for slow startup. TCP success only proves a port accepts connections.

Checks never roll back automatically; use Health checks and rollback to decide next steps.

Update timeout¶

Pause new automatic executions. Inspect actual images, service state, and platform events in Docker / Portainer / Kubernetes / Helm, then compare execution history. A timed-out write may already have been accepted; do not assume “nothing happened” and immediately repeat it.

Distinguish source-fetch timeouts, control-plane request timeouts, and probe timeouts. Runtime operation policy is not a deadline for the entire upgrade.

Missing or invalid snapshot¶

Check the support matrix, whether a snapshot-producing update ran, and whether retention removed it. legacy_unverified does not mean corrupted; invalid must not be used for recovery. Inspect the preview API result rather than editing digests to bypass checks.

Notification not received¶

Send a test, then check that the notifier is enabled, its channel type matches the endpoint, event subscriptions, public addressing and allowed ports, and the receiver's rate limits, keyword or signing settings. Failed messages are retried up to 4 times and never replayed afterwards; see Notifications.

Repository webhook does not trigger a refresh¶

Check the repository webhook's delivery log. No entry: make sure the Git platform can reach the endpoint and BASE URL. Signature failure: compare the secret and authentication mode. Ignored event: check event types and branch/workflow filters. A received event still refreshes under source rules; if no new version appears, follow Missing versions.

Deployment awaits approval or is blocked¶

Open the task details for the reason. For first onboarding, configuration drift or version limits, review the plan and approve it. If another instance or executor owns the target or its markers conflict, approval is not possible; resolve ownership first. See Deployment plan approval.

Startup, write, or migration failure¶

Read the actual logged error. Check the mount path, write permissions, disk space, and filesystem restrictions; do not broadly loosen permissions recursively.
Ensure only one instance is active and its database matches system-secrets.json.
For migration issues, stop and back up before using the migrate entry command. Do not edit live tables manually.
For downgrades or inconsistent data, follow Recovery with matching versions.

Include the version, deployment method, reproduction steps, and redacted logs in issues, not real databases, key files, or complete snapshots.