# Troubleshooting

> The failures an administrator fixes — sign-in, access, deploys, builds, storage, startup and keys.

Source: /toft-docs/latest/admin/operate/troubleshooting/

Start at **Admin → [Checks](/toft-docs/latest/admin/operate/checks.md)**. It is faster than the logs and catches
failures that are reported nowhere else.

## Sign-in and access

| Symptom | Cause and fix |
|---|---|
| Nobody can sign in | Sign in as the [built-in administrator](/toft-docs/latest/admin/identity/local-administrator.md). If local sign-in is off, run `toft local-admin enable` on the host |
| Signed in, no access | Expected: no first-user-becomes-admin rule, and a provider grants nothing. Make them an administrator or add them to a [group](/toft-docs/latest/admin/identity/groups.md). If they see a refusal, check whether the provider is set to wait for [activation](/toft-docs/latest/admin/identity/activation.md) |
| Directory group memberships never appear | The **Directory groups** check warns when mappings exist but no membership arrived. Check the claim name, the requested scopes, and whether the IdP must enable the groups claim. A claim of unexpected shape reads as absent |
| Directory feed does nothing | `skip` = no token; `warn` = token never used, so the IdP is not calling. `/scim/v2/*` answers 401 (not 404) without a token |
| Public apps ask people to sign in | [Anonymous access](/toft-docs/latest/admin/security/anonymous.md) is off, so public means signed-in. Turn it on and they are public again |
| Everyone sees every app's name | [`apps_listable_to_authenticated`](/toft-docs/latest/admin/apps/listing.md), on by default. One toggle turns it off |
| Every audit-log address is the load balancer's | Set `TRUSTED_PROXY_CIDRS`; the **Trusted proxy** check flags it |

## Apps and deploys

| Symptom | Where to look |
|---|---|
| Public but unreachable from outside | Rarely the app: DNS, proxy, apps origin, TLS. See [Reachability](/toft-docs/latest/admin/security/reachability.md); `unknown` is not `not_ok` |
| Deploy refused, "worked yesterday" | [Dependency policy](/toft-docs/latest/admin/security/dependencies.md) (a new advisory refuses deploys, never the running app) · [Trusted sources](/toft-docs/latest/admin/security/sources.md) · [Language versions](/toft-docs/latest/admin/build/languages.md) (removed interpreter) · [Clone credentials](/toft-docs/latest/admin/security/git-connections.md) (expired) · [Locks](/toft-docs/latest/admin/apps/locking.md) |
| Builds queued, not starting | **Admin → Processes → Build queue**, then the build concurrency setting, then host memory. Next.js and R builds are the usual culprits; a [binary R repository](/toft-docs/latest/admin/build/languages.md) helps most |
| App restarts repeatedly | See [crashes and restarts](/toft-docs/latest/admin/operate/health-and-processes.md#crashes-and-restarts). Read the app's logs, and check its memory limit before blaming the owner |
| Browser uploads to storage fail, nothing logged | Bucket CORS — Toft never saw the request. See [App storage](/toft-docs/latest/admin/capabilities/storage.md) |
| Gallery is empty | It is off by default. If on and empty, the catalog may need a newer Toft — you are told so |
| Metrics stopped | Not an outage. Check the collector endpoint and `METRICS_ADDR` (its own listener, never a path on `:8080`) |

## The install will not start

Read the exit message; every refusal names its reason. Common ones:

- `JWT_SECRET` under 32 bytes.
- A database below the schema floor — upgrade through the intermediate release
  ([Upgrading](/toft-docs/latest/admin/start/upgrading.md)).
- Both isolated backends configured.
- An unknown artifact or store backend, or an unknown KEK scheme.
- A boolean it cannot read: only `1/true/yes/on` and `0/false/no/off` (or unset) are accepted.

## A secret will not decrypt

The error names the missing key. Put it in `ENCRYPTION_KEY_OLD` and restart. See
[At-rest encryption](/toft-docs/latest/admin/security/encryption.md).