---
title: "Deployment Troubleshooting"
description: "Common deployment issues and first-line diagnostics."
source: "Guardian Platform"
---
Use this page for first-line deployment checks before escalating.

Each section below starts from one of these readiness checks. `$API_SECRET` is the Auth Service API secret, `global.secrets.authService.values.apiSecret` in `secrets.yaml` (key `api-secret` in the `platform-auth-service` secret):

```bash
# Sign-In Fails
curl https://guardian.example.com/authService/health/ready
# Attachments Fail, Indicators Do Not Evaluate
curl https://guardian.example.com/governanceService/health/ready
# Certificates or Lineage Fail
curl https://guardian.example.com/integrityService/health/v1
curl -H "Authorization: Bearer $API_SECRET" \
  https://guardian.example.com/authService/health/signing
```

## Install or Upgrade Fails

Confirm the chart version matches the release manifest, values are valid for the selected identity provider, and all required secrets are available in the target namespace.

Many configuration mistakes stop Helm before anything reaches the cluster. To see the error without installing, render the chart with the same chart version and values files:

```bash
helm template guardian-platform \
  oci://ghcr.io/eqtylab/charts/guardian-platform \
  --version <chart-version> \
  --namespace guardian \
  --values values.yaml \
  --values secrets.yaml
```

Common render errors:

- **`global.secrets.<name>.values.<key> is required when … create is true`:** `secrets.yaml` sets `global.secrets.create: true` but leaves that value empty. Fill it in, or set `create: false` and [pre-create the secret](./chart-values.mdx#pre-created-secrets).
- **`global.secrets.database.values.gatewayDsn is required when create and gateway-stack are enabled`:** add the `guardian_gateway` DSN beside the database password.
- **`No database configured`:** `postgresql.enabled` is false and `global.postgresql.host` is empty. Enable the bundled PostgreSQL or point at an external database.
- **`Original containers have been substituted for unrecognized ones`:** the bundled PostgreSQL image was redirected to a mirror without `postgresql.global.security.allowInsecureImages: true`.
- **`platformAdminEmail is required when … createPlatformAdmin is true`:** set the admin email for the identity provider's post-install setup.

## Images Do Not Pull

Confirm registry access, image pull secrets, registry override values, and mirrored image digests for restricted environments.

`ImagePullBackOff` usually means one of:

- The `platform-image-pull-secret` secret is missing, or its registry does not match the image registry (for example Cloudsmith credentials with GHCR images, without `values-cloudsmith.yaml`).
- The entitlement token is a dev token used against `eqtylab/prod`, or has been revoked.
- An image tag was overridden to one the registry does not hold; leave image tags unset.
- In a restricted environment, an upstream image was not mirrored or its setting was not redirected.

## Sign-In Fails

Confirm identity provider mode, issuer, audience, client settings, callback URLs, and Guardian public domain.

## Attachments Fail

Confirm object storage provider, bucket or container permissions, network access, and customer storage policies.

## Certificates or Lineage Fail

Confirm Integrity Service readiness, key-management access, and credential configuration.

## Indicators Do Not Evaluate

Confirm Governance Service readiness, event integration configuration, active indicator applications, and project context.

## Related

- [Known Issues](./known-issues.mdx) — release advisories that may already explain the symptom
- [Auth Service Operations](../auth-service/operations.mdx) — deeper checks for sign-in, membership, and signing failures
- [Governance Service Operations](../governance-service/operations.mdx) — readiness, attachment, and indicator symptoms
- [Integrity Service Troubleshooting](../integrity-service/troubleshooting.mdx) — certificate and lineage symptoms
- [Observability](./observability.mdx) — the signals to watch and what to include when escalating
- [Release Manifest](./release-manifest.mdx) — the chart version and image digests to compare against