---
title: "First-Run Troubleshooting"
url: "https://docs.caracal.run/v1.0/get-started/first-run-troubleshooting/"
markdown_url: "https://docs.caracal.run/markdown/v1.0/get-started/first-run-troubleshooting.md"
description: "Fix common install, readiness, sign-in, identity, mandate, Gateway, upstream, and audit issues during onboarding."
page_type: "workflow"
concepts: []
requires: []
---
# First-Run Troubleshooting
Canonical URL: https://docs.caracal.run/v1.0/get-started/first-run-troubleshooting/
Markdown URL: https://docs.caracal.run/markdown/v1.0/get-started/first-run-troubleshooting.md
Description: Fix common install, readiness, sign-in, identity, mandate, Gateway, upstream, and audit issues during onboarding.
Page type: workflow
Concepts: none
Requires: none
---
Use this page when a Get Started step fails. Every request you make crosses the same boundaries in the same order, so diagnose in that order and stop at the first boundary that fails - do not change policy, credentials, and routing at the same time:
```mermaid
flowchart LR
Ready[Stack readiness] --> SignIn[Console sign-in] --> Identity[Application identity] --> STS[Token service] --> GW[Gateway] --> Up[Upstream service] --> Audit[Audit trail]
```
Run the failing step once and keep its request ID or exact error, then start at the matching section below. For production incidents and deeper operational diagnosis, use [Troubleshoot by Symptom](/v1.0/operations/troubleshooting/).
## Readiness Failures
The same command works in every shell:
```sh
caracal status --ready --json
```
| Symptom | Check |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| Docker command fails | Confirm Docker Desktop or Docker Engine is running and `docker compose version` succeeds. |
| A service is not ready | Wait for the dependency named in the JSON output, then rerun readiness. |
| Ports are already in use | Stop the local process holding the port; the local port map is in [Defaults and Limits](/v1.0/reference/defaults-and-limits/#ports). |
| Stack state looks stale | Run `caracal down`, then `caracal up`. Use `caracal purge` only when you intentionally want to remove local state. |
## Console Sign-In
| Symptom | Check |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Sign-up is rejected or the access-denied page appears | The packaged console closes registration by default and shows one uniform page for every allowlist denial. On the runtime host, run `caracal allowlist list` to inspect entries, then `caracal allowlist add ` or `caracal allowlist unlock ` - see [Control Console Access](/v1.0/runtime-console/console-access/). Make sure a sign-in method is configured in `$CARACAL_HOME/caracal.env` - see [Enable Console Sign-In](/v1.0/get-started/install-caracal/#enable-console-sign-in). |
| Google or GitHub buttons are missing | Set both the client ID and client secret for the provider, then rerun `caracal up`. |
| The provider rejects sign-in with a redirect URI mismatch (Google shows `Error 400: redirect_uri_mismatch`) | The OAuth client does not list the console's callback URL. The packaged console signs in through `http://localhost:3001/api/auth/callback/google` (or `.../github`); a source-checkout `caracal web` session uses port `3002` instead, and a custom `CARACAL_WEB_URL` moves the origin with it. Add the packaged callback to the OAuth client - Google accepts several redirect URIs, while a GitHub OAuth app takes one callback URL per app - then retry; no stack restart is needed. |
| Password sign-in is blocked pending verification | The packaged console requires a verified email. Confirm `CARACAL_SMTP_URL` and `CARACAL_SMTP_FROM` are set and the verification message was delivered. |
## Application Identity Issues
| Symptom | Check |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `Caracal.fromEnv: provide CARACAL_APP_CLIENT_SECRET` or a similar constructor error | Export `CARACAL_ZONE_ID`, `CARACAL_APPLICATION_ID`, and `CARACAL_APP_CLIENT_SECRET` exactly as in [Give the Agent Its Identity](/v1.0/get-started/first-protected-call/#give-the-agent-its-identity), or set `CARACAL_CONFIG` to a complete profile. |
| SDK cannot load configuration | `CARACAL_CONFIG` must name an existing profile file; a missing file at that path is an error, not a fallthrough. |
| Authentication is rejected (401) | The client secret no longer matches the application - reveal the current value from the application's detail panel, or rotate it and update your environment or secret file. |
| Secret file is rejected | Ensure the file named by `app_client_secret_file` exists and is readable only by the current user. |
## Lost Application Secret
The application client secret is held sealed server-side. If you lose your local copy, reveal it again from the application's detail panel in the web console - each reveal is recorded in the zone audit timeline - or rotate the secret and update your environment or secret file with the new value.
## Token Service Denials (STS 403)
The STS is Caracal's token service: it checks policy and issues mandates. A 403 from it means your program authenticated successfully but policy did not allow what it asked for.
| Check | Fix |
| ----------------- | ------------------------------------------------------------------------------------------- |
| Active policy set | Activate the starter policy set created by guided setup. |
| Resource ID | Use the resource ID you created in guided setup. |
| Scopes | Request only scopes covered by the starter policy. |
| Audit request ID | Open web console **Audit** with the request ID to see the policy diagnostic. |
## Gateway 403
A Gateway 403 means policy already said yes and a mandate was issued, but the Gateway rejected the request before forwarding it upstream.
| Check | Fix |
| -------------------- | ------------------------------------------------------------------------- |
| Authorization header | The SDK transport attaches `Authorization: Bearer `; send requests through it rather than a plain HTTP client. |
| Resource header | The SDK sets `X-Caracal-Resource` from the resource ID you pass; confirm it matches guided setup. |
| Mandate freshness | Mandates are short-lived and single-use by design; rerun the example to mint a fresh one. |
| Revocation | Confirm the session, application, or delegation was not revoked. |
| Route binding | Confirm the resource has the Gateway route and upstream URL you intended. |
## Upstream Unreachable
| Symptom | Check |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| Connection refused | The upstream service is not listening, or the Gateway cannot reach that host and port. |
| DNS failure | Use a hostname visible from the Gateway container, not only from the host shell. |
| Demo upstream missing | Confirm the resource's upstream URL is reachable from the Gateway container and the provider key sealed on the provider is current. |
| Wrong path | Use a known-good path on the upstream before trying custom paths. |
## Missing Audit Events
| Check | Fix |
| ------------------------------------ | --------------------------------------------------------------------------------- |
| Wrong request ID | Copy the request ID from the STS, Gateway, SDK, or web console output. |
| Wrong zone | Select the zone used by guided setup. |
| Request never reached STS or Gateway | Confirm the example used your configuration and the Gateway URL it derives. |
| Audit ingestion lag | Wait briefly and refresh the web console audit view. |
## Expected Outcome
Repeat only the failed step. Success means readiness passes, the protected call returns the upstream response, and Audit contains both the authorization decision and the Gateway result under the same request trace.
## Next Step
After the first run succeeds, continue with [Tutorials](/v1.0/tutorials/) or the language-specific [SDK guides](/v1.0/guides/).