# Troubleshooting

> Fixes for the common failures in a self-hosted installation, from containers to links and login.

Source: https://docs.grovs.io/docs/self-hosting/operate/troubleshooting

## Which containers should run?

Every service except `migrate` should be running; `proxy` only on standalone deployments. `migrate` must exit with code 0, or the application does not start. [Containers](https://docs.grovs.io/docs/self-hosting/operate/monitoring#containers) lists each healthcheck.

From the installation directory:

```bash
docker compose ps -a
docker compose logs --tail=100 migrate web worker-1 worker-2
docker compose logs --tail=100 postgres redis clickhouse
```

On cloud VMs, run these as root from `/opt/grovs`. In Coolify and Dokploy, use the service logs. For a local trial, add `-f docker-compose.yml -f docker-compose.local.yml` after `docker compose`.

## Images cannot be pulled

- Check `GROVS_VERSION` against the [latest completed release](https://github.com/grovs-io/self-host/releases/latest), or use `latest` in an existing Compose installation.
- The images are `ghcr.io/grovs-io/backend` and `ghcr.io/grovs-io/dashboard`. Both GHCR packages must contain the selected tag and allow anonymous pulls.
- On Railway templates and Render, check the service image sources directly.
- A public source repository does not make its packages public automatically.
- An image built only locally is not available to new servers until the release workflow pushes it.

See [Images and releases](https://docs.grovs.io/docs/self-hosting/configure/images).

## Dashboard works, project links fail

Check all three:

1. Wildcard DNS points to the correct server, including `*.test.<links-domain>`.
2. The reverse proxy routes the project hostname to `web:3000`.
3. The certificate covers that hostname. `*.<links-domain>` does not cover `<project>.test.<links-domain>`; the test domain needs its own wildcard.

In the platform template, the dashboard's router has higher priority than the API and link router. Keep `GROVS_ROUTER_PREFIX` unique on a shared proxy. The `GROVS_*_DOMAIN_PATTERN` values are generated from your link domains; update them too if you change domains.

## Coolify or Dokploy reports a proxy or certificate error

- The external Docker network exists and the Traefik proxy is connected to it.
- The entrypoint and certificate resolver names match the platform environment file.
- The resolver uses DNS-01. The template uses Traefik v3 `HostRegexp` rules, and wildcard certificates need DNS-01.
- The standalone Caddy profile is off.

## Login fails after a successful migration

The API and dashboard must share the same `OAUTH_CLIENT_UID` and `OAUTH_CLIENT_SECRET`. Import the complete generated environment; do not generate credentials separately per service. Confirm the dashboard container can reach `API_HOST`.

## Analytics is temporarily unavailable

Wait for the first scheduled rollup, then check the `worker-1` and ClickHouse logs. Confirm all three databases are healthy. Do not disable the shipped ClickHouse flags to hide an error; ClickHouse is the analytics and event store.

## Uploaded images do not show

`S3_ASSET_PREFIX` must be `https://<API_HOST>`, and that host must be publicly reachable over HTTPS. See [Configuration](https://docs.grovs.io/docs/self-hosting/configure/configuration#uploaded-images-must-be-reachable).

## Reset everything

For a local trial, see [Stop and resume](https://docs.grovs.io/docs/self-hosting/get-started/try-locally#stop-and-resume). For a public installation, back up your data and secrets first. Restarting containers keeps volumes; `docker compose down --volumes` deletes them.