Troubleshooting

Start with the failing request, its HTTP status, and the relevant access warning or log entry. A response can originate from Middlewarr, your front reverse proxy, or the upstream service.

The container exits at startup

Run:

docker compose logs --tail=100 middlewarr

Check that data/settings.yml exists on the host, that ./data is mounted at /data, and that the container can write there. Middlewarr requires the settings file and a writable SQLite database directory.

For template or OpenAPI download failures, check outbound DNS and network access. Cached copies can help an existing installation, but a first run may not have them yet.

The dashboard will not open

Check that the container is running, host is 0.0.0.0, and the host port is published to container port 80. With the example Compose file, open port 9292.

Test http://YOUR_HOST:9292/health from a machine that should have access. If it works directly but not through your HTTPS hostname, inspect the front reverse proxy’s routing.

Setup asks for a bootstrap token

Copy the token from the startup log line containing “one-time token” into the setup screen’s Bootstrap token field. It is required for requests that do not reach the server from loopback.

A browser on the host can still appear remote through container networking or a reverse proxy. Supplying the token is the supported way to complete that setup; you do not need to disable the check.

Sign-in does not stay signed in

Check auth.cookieSecure. Use false for a plain-HTTP site and true when the browser uses HTTPS. Also check that the reverse proxy forwards cookies.

Sessions expire after 24 hours idle or 30 days total. A password change or administrator recovery revokes sessions, so sign in again afterward.

Saving settings returns 403

Administration writes require a valid session and an accepted origin. When using a reverse proxy, preserve the browser-facing Host and the Origin header. Do not substitute the internal container hostname as Host.

A proxy API key cannot replace an administration session. See Security and HTTPS.

A proxy returns 401

Check, in order:

1. The URL contains the correct /proxy/{appSlug} prefix.
2. The app and target proxy are active, and the app has a configured proxy.
3. The client supplies that proxy’s key, not the service’s original key.
4. The key has not been rotated.
5. If both a header and query key are present, the X-Api-Key header is the intended one; it takes precedence.

Use Tools → Warnings to distinguish these cases. An upstream 401 after an allowed request can instead indicate an invalid service key.

A proxy returns 403

An Endpoint not enabled warning means the requested method and path are outside the effective allowlist. Review the warning and the proxy’s Endpoints tab.

Do not grant every endpoint just to silence the error. A template may not cover the integration’s current version or every optional feature. Grant the required operation only after reviewing it.

An endpoint cannot be enabled from a warning

The grant flow requires the path and method to match the service’s cached OpenAPI specification. Open Settings → OpenAPI, check the cache, and sync if needed.

A concrete path may resolve to a parameterized path that grants access to more than one resource. If the call remains absent from the upstream specification, investigate the integration and service versions before changing your template or policy.

A proxy returns 502

Middlewarr uses 502 for upstream transport failures, such as a refused connection or failed DNS lookup. Check the service URL from the container’s network, the upstream process, and any firewall or TLS certificate error shown in the logs.

Do not use localhost to refer to a separate container. If using a service hostname, confirm both containers share the Docker network where that name resolves.

A service cannot be added

Middlewarr probes the instance before saving it. Use its base URL, include any configured URL base, and omit the API-version suffix. Check the original upstream API key.

Service names, URLs, and upstream keys must be unique. If adding a second instance, configure a distinct instance name upstream.

A removed template permission is still allowed

Template sync can preserve previously served methods as local overrides. Open the proxy’s Endpoints and History tabs and review the preserved path. Explicitly remove the grant if you want it revoked. See template sync behavior.

Forgotten administrator password

Recovery requires host access. It clears the administrator account and all administration sessions, while retaining services, apps, proxies, and their configuration.

1. Add MIDDLEWARR_RESET_ADMIN: "1" under the service’s environment section in compose.yaml.
2. Recreate the container with docker compose up -d --force-recreate middlewarr.
3. Read docker compose logs --tail=100 middlewarr and copy the new bootstrap token.
4. Open the dashboard and create a new administrator using that token.
5. Remove MIDDLEWARR_RESET_ADMIN from the Compose file and recreate the container again with the same command.
6. Confirm you can sign in with the new credentials.

Remove the reset variable

Leaving the variable enabled repeats the reset on every startup. A normal docker compose restart does not apply changes to container environment variables; recreate the container after editing the Compose file.

Report a problem

Include the application source revision, the integration and upstream versions, the operation that failed, the status code, and relevant redacted logs. Explain whether the failure also occurs when reaching Middlewarr directly on its trusted network.

Remove keys, bootstrap tokens, cookies, notification URLs, and sensitive query values before sharing diagnostic material.