# Troubleshooting

## Image pull reports `manifest unknown`

Confirm that the `v1.0.0` Release has been published and that `.env` contains the immutable production tag:

```dotenv
CONDUCTOR_IMAGE=gitea.skeletonworks.online/vwiebe/conductor
CONDUCTOR_VERSION=v1.0.0
```

Do not substitute `latest`. The production release must pull anonymously; if the registry requests a login after publication, report a release-distribution failure rather than adding private credentials to the installation.

## Image pull reports no matching platform

The v1.0.0 production image supports Linux/AMD64 only. Confirm `uname -m` reports `x86_64`. ARM64 is not a supported v1.0.0 target.

## Container exits immediately

Inspect logs. Production intentionally refuses to start when `CONDUCTOR_SECRET_KEY` is not a valid 32-byte base64/hex value or `CONDUCTOR_SESSION_KEY` is shorter than 32 bytes.

## Container is unhealthy

```bash
docker compose --env-file .env -f compose.production.yml ps
docker compose --env-file .env -f compose.production.yml logs --tail=200 conductor
curl -v http://127.0.0.1:8080/api/health
```

Confirm `/data` is writable by UID/GID 10001. Restore tooling resets database ownership to `10001:10001` and mode `0600`.

## Setup or login does not persist in the browser

Production cookies are marked `Secure`. Use the final `https://` hostname, not a plain-HTTP server IP or hostname. The loopback HTTP endpoint exists for host health checks.

## Stored credential no longer works after restore

The restored database and `CONDUCTOR_SECRET_KEY` likely do not match. Restore the complete archive, including its `.env`/`.secrets`. Credential encryption cannot be bypassed or recovered without the original key.

## Published deep link returns proxy 404

The reverse proxy must send all non-API paths to Conductor rather than serving static files independently. Test the container directly at `/apps/<app>/<page>` and use the Caddy/NGINX examples in `docs/INSTALL.md`.

## REST request is blocked

Read the safe error code and `docs/PROXY_SECURITY.md`. Private/internal destinations are denied unless their exact origin is configured in `CONDUCTOR_PROXY_INTERNAL_ORIGINS`. Do not add broad exceptions.

## Browser shows old controls after upgrade

Confirm the running image tag/digest, then perform a hard browser refresh. The production `index.html` is sent with `no-cache`; hashed assets may be cached safely.

## Backup refuses to run

The application container must be running and the environment file must exist because it contains recovery keys. Check Compose project selection and paths. SkeletonWorks commands require the exact `--fqdn` used during setup.