---
title: "Troubleshooting | DRAWBRIDGE docs"
description: "What to check when sign-in, signing or the rig misbehaves, and how to read the gateway's plain answers and reason codes."
url: https://drawbridge.apps.wayne.edu/docs/troubleshooting.html
llms: https://drawbridge.apps.wayne.edu/llms.txt
generator: Squire agent-ready
---

# Troubleshooting [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#troubleshooting)

This page matches the answers the gateway gives by design (a refusal to start, a 503, a bare 401, a session that is gone) to their causes, and gives the command that checks each one.

## Startup [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#startup)

### The entrypoint refuses to start [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#the-entrypoint-refuses-to-start)

Cause: the gateway cannot start without the two files and the two secrets it is given: `drawbridge.yaml` (the per-app config), `signing.key` (the ES256 key that signs assertions), `DRAWBRIDGE_OIDC_CLIENT_SECRET` (the Entra client secret) and `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE` (at least 32 characters). The entrypoint refuses to start if any is missing, and `render` refuses an unusable secret, so Apache never starts with a literal `${...}` for a secret. A config error stops the container from starting.

Fix: mount the two files read-only, put both environment variables in the deployment's secret store, keep the passphrase at 32 characters or more, and make sure the config validates.

Check:

```sh
php bin/drawbridge config:validate --config=config/drawbridge.yaml
```

### config:validate reports problems [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#config-validate-reports-problems)

Cause: `config:validate` checks the config and prints every problem at once, then the provider settings (never the secret, only whether its variable is set); it exits 1 if there is anything to report. Typical findings are a path rule that uses a wildcard or a regular expression (there are no wildcards and no regular expressions), an issuer that is not https (plain http is accepted only for a `.test` host), or a value outside its range.

Fix: read the printed lines, correct `config/drawbridge.yaml`, and run the check again until it is clean.

Check:

```sh
php bin/drawbridge config:validate --config=config/drawbridge.yaml
```

## Sign-in and sessions [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#sign-in-and-sessions)

### An api path answers a bare 401 [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#an-api-path-answers-a-bare-401)

Cause: this is the answer by design when the session is gone. A request for an api path without a session gets a plain 401, so a script never receives an HTML login page; the 401 carries no Location header. The session can be dead because either clock ran out (8 hours total, 1 hour idle by default), the visitor signed out through the `?logout=` link, or the gateway was restarted or reloaded (the cache lives in shared memory and starts empty).

Fix: have the caller sign in again; nothing on the gateway side is broken. If a 401 appears where a redirect to sign in was expected, the path is listed under `api` instead of `protected`.

Check:

```sh
php bin/drawbridge explain app1.apps.wayne.edu /api/ --config=config/drawbridge.yaml
```

### Sessions are empty after a reload or restart [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#sessions-are-empty-after-a-reload-or-restart)

Cause: by default (`gateway.session_store: shm`) drawbridge keeps the gateway sessions in Apache's shared memory, and every restart or graceful reload rebuilds that store empty. The pinned mod_auth_openidc accepts the documented two-value form (a current plus a previous passphrase, `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS`) and starts with it, but the previous passphrase can only decrypt a session whose state still exists, so it cannot keep anyone signed in across any restart or reload: the saved cookie is refused and the browser is sent to sign in again. The `rotation` rig run documents this against the pinned module, with the old passphrase kept, with it dropped, and after the gateway container is recreated.

Warning

With the default store, changing `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE` and restarting signs everyone out (safe, but noisy). Rotation stays: set the new value, restart, expect everyone to sign in again. With a shared session store it is graceful: with `gateway.session_store: redis` (0.2.1) set the old value as `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS` and nobody is signed out, proven by `rig/run.sh redis-rotation`. The steps are in [Changing the passphrase](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html#changing-the-passphrase).

Fix: none to apply with the default store; this is the expected behavior. Schedule the change for a moment when a mass re-sign-in is acceptable, and tell the app owners.

Check:

```sh
php bin/drawbridge config:validate --config=config/drawbridge.yaml
```

## Signing [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#signing)

### A protected path answers 503 [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#a-protected-path-answers-503)

Cause: the signer could not sign. If the signer cannot sign, the answer is 503 and the request does not reach the app. There is no unsigned mode: an app gets the signed assertion or nothing (the header modes were removed for 1.0). The usual cause is the mounted key: the ES256 private key at `DRAWBRIDGE_SIGNING_KEY_FILE` (default `/run/drawbridge/signing.key`) is missing or unreadable, or `DRAWBRIDGE_SIGNING_KEY_ID` no longer matches the key. Every end-to-end sign-in in the rig fails if the signer cannot read the mounted key.

Fix: make sure the key file is mounted read-only where `DRAWBRIDGE_SIGNING_KEY_FILE` points and that the signer can read it, and change `DRAWBRIDGE_SIGNING_KEY_ID` when the key changes. `keys:generate` makes a fresh ES256 key pair; it refuses to overwrite a file. The signer's log carries exactly one reason-code line per refused request, with no subject, attribute or token; a signing failure logs only the exception class, never its message.

Check:

```sh
php bin/drawbridge config:validate --config=config/drawbridge.yaml
```

### Every app refuses sign-ins with `gateway.signature` after a key switch [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#every-app-refuses-sign-ins-with-gateway-signature-after-a-key-switch)

Cause: the gateway now signs with a key the apps do not trust. The `kid` in `DRAWBRIDGE_SIGNING_KEY_ID` is not in the apps' key set file, or the private key at `DRAWBRIDGE_SIGNING_KEY_FILE` is not the one published under that `kid`. This happens when the gateway switched to a key that was never published as the "next" key.

Fix: switch the gateway back to the previous key and `kid` (the apps still trust it), publish a key set file that holds the new key, wait until the apps have it, and switch again. The [rotation guide](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html) has the order that avoids this.

Check:

```sh
php bin/drawbridge keys:jwks --key=<kid>=<the public half of the key the gateway signs with>
```

The printed `kid`, `x` and `y` must match an entry in the file the apps read.

## Path rules [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#path-rules)

### A path goes to sign-in that should be public [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#a-path-goes-to-sign-in-that-should-be-public)

Cause: a path with no rule gets `login` unless the app says otherwise; public is a decision, not a default. Remember how rules match: exact (`/up`) or prefix (a trailing slash, `/assets/`), the longest rule wins, an exact rule beats a prefix of the same length, and query strings are never part of the match. A path with an encoded slash, a backslash, a semicolon, a control character or bad UTF-8 is treated as `login` (and the guard answers 400), so a mangled URL also lands on sign-in.

Fix: add the path to the app's `public` list in `config/drawbridge.yaml` (or to whichever list it belongs to), and re-check what the gateway will do with the request.

Check:

```sh
php bin/drawbridge explain app1.apps.wayne.edu /admin/users --config=config/drawbridge.yaml
```

`explain` says which rule applies to a request, and which authentication context it needs, and why.

### An unknown host answers 403 [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#an-unknown-host-answers-403)

Cause: the request arrived for a host with no app entry in the config, or for a refused path. The default catch-all host answers 403 with its own error page.

Fix: add the app to the config (host, upstream, and which paths are public, protected, step-up or API) and re-render, or correct the address the visitor asked for.

Check:

```sh
php bin/drawbridge explain <app host> /up --config=config/drawbridge.yaml
```

## Related [#](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html#related)

- [First deployment](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html)
- [How it works](https://drawbridge.apps.wayne.edu/docs/guides/how-it-works.html)
- [Sessions and lifetimes](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html)
- [Protecting paths](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html)
- [Configuration](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html)
- [Commands](https://drawbridge.apps.wayne.edu/docs/reference/commands.html)
