---
title: "First-Run Troubleshooting"
url: "https://docs.caracal.run/get-started/first-run-troubleshooting/"
markdown_url: "https://docs.caracal.run/markdown/get-started/first-run-troubleshooting.md"
description: "Fix common install, readiness, profile, STS, Gateway, upstream, and audit issues during onboarding."
page_type: "workflow"
concepts: []
requires: []
---

# First-Run Troubleshooting

Canonical URL: https://docs.caracal.run/get-started/first-run-troubleshooting/
Markdown URL: https://docs.caracal.run/markdown/get-started/first-run-troubleshooting.md
Description: Fix common install, readiness, profile, STS, Gateway, upstream, and audit issues during onboarding.
Page type: workflow
Concepts: none
Requires: none

---

Use this page when the Get Started path fails before your first protected call or first SDK integration succeeds. For production incidents and deeper operational diagnosis, use [Troubleshoot by Symptom](/operations/troubleshooting/).

## Readiness Failures

Run:

```sh
caracal status --ready --json
```

On Windows PowerShell:

```powershell
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 conflicting local process or change the runtime port configuration before starting Caracal. |
| Stack state looks stale | Run `caracal down`, then `caracal up`. Use `caracal purge` only when you intentionally want to remove local state. |

## Profile Issues

| Symptom | Check |
| --- | --- |
| `CARACAL_CONFIG` is missing | Set it to the profile path shown by guided setup. |
| Profile path is wrong | Open the generated TOML file and confirm it matches the current zone, application, Gateway, STS, and secret-file path. |
| Secret file is rejected | Ensure the secret file exists and is readable only by the current user. |
| SDK cannot load configuration | Start the process from a shell that has `CARACAL_CONFIG` set, or pass the profile path using the SDK-supported configuration mechanism. |

Linux and macOS:

```sh
export CARACAL_CONFIG=/path/to/caracal.toml
```

Windows PowerShell:

```powershell
$env:CARACAL_CONFIG = "C:\path\to\caracal.toml"
```

## Console File Writes

If guided setup does not write files:

1. Copy the generated TOML profile from the result view.
2. Save it at the profile path shown by the Console.
3. Copy the one-time app client secret into the secret-file path shown by the Console.
4. Restrict the secret file so only the current user can read it.
5. Rerun the first-success command from the result view.

The app client secret is shown once for newly created apps. If you lose it, create a new secret from the Console and update the profile.

## STS 403

An STS 403 means the workload authenticated but did not receive a mandate.

| Check | Fix |
| --- | --- |
| Active policy set | Activate the starter policy set created by guided setup. |
| Resource ID | Use the resource ID from the guided setup result view. |
| Scopes | Request only scopes covered by the starter policy. |
| App secret | Regenerate the app secret if the configured secret file no longer matches the app. |
| Audit request ID | Open Console **audit** or **explain** with the request ID to see the policy diagnostic. |

## Gateway 403

A Gateway 403 means the Gateway rejected the request before forwarding it upstream.

| Check | Fix |
| --- | --- |
| Authorization header | Send `Authorization: Bearer <Caracal access token>`. |
| Resource header | Send `X-Caracal-Resource` with the resource ID from guided setup. |
| Token freshness | Rerun the workload to obtain a fresh short-lived mandate. |
| Revocation | Confirm the session, app, or delegation edge 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 | Start `caracalDemoUpstream` on the `caracalData` Docker network or use your own reachable service. |
| Wrong path | Use the first request path from the Console result view before trying custom paths. |

## Missing Audit Events

| Check | Fix |
| --- | --- |
| Wrong request ID | Copy the request ID from the STS, Gateway, SDK, or Console output. |
| Wrong zone | Select the zone used by guided setup. |
| Request never reached STS or Gateway | Confirm the workload used the generated profile and the Gateway URL from that profile. |
| Audit ingestion lag | Wait briefly and refresh the Console audit view. |

## Next Step

After the first run succeeds, continue with [Tutorials](/tutorials/) or the language-specific [SDK guides](/guides/).