First-Run Troubleshooting

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.

Readiness Failures

Run:

caracal status --ready --json

On Windows 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:

export CARACAL_CONFIG=/path/to/caracal.toml

Windows 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 or the language-specific SDK guides.