After upgrading an OpenClaw installation, the dashboard suddenly stopped working. The browser displayed a connection error, while the reverse proxy returned a 502 Bad Gateway response.

At first, the problem appeared to be related to DNS, HTTPS, Tailscale, or authentication. The real cause was different: the OpenClaw Gateway was refusing to become ready because of a stale database migration artifact.

This article explains how we diagnosed the issue, repaired it safely, and separated the Gateway problem from unrelated AI provider errors.

The symptoms

The failure appeared in several places:

The OpenClaw dashboard would not connect.
The reverse proxy returned 502 Bad Gateway.
The Gateway container repeatedly restarted.
The browser reported that the site could not be reached.
Gateway logs showed that startup migrations had not completed cleanly.
Some assistant requests failed even after the Gateway was repaired.

The important lesson is that these symptoms can have different causes. A working HTTPS page does not necessarily mean the Gateway is healthy, and a healthy Gateway does not guarantee that every AI provider is available.

The first investigation

The first step was to inspect the live containers and their restart status:

docker ps -a
docker inspect openclaw-gateway
docker logs --since 10m openclaw-gateway

The Gateway was running in a restart loop. Its logs contained messages similar to:

OpenClaw startup migrations did not complete cleanly;
refusing to report the gateway ready.

The logs also identified a Memory Core migration conflict involving a legacy SQLite file:

Left migrated Memory Core legacy memory index sidecar in place
because the migrated file already exists.

This explained why the reverse proxy returned 502: the proxy was running, but the Gateway behind it was not ready to accept requests.

The real root cause

The root cause was a stale SQLite migration sidecar.

During a previous migration, OpenClaw had created a migrated Memory Core database file. A later startup detected that the same migration artifact was still present and treated it as an unresolved migration conflict.

The current canonical database and the migrated sidecar contained the same data, but OpenClaw still needed the stale artifact moved out of the active migration path before startup could complete.

The problem was not:

DNS
The HTTPS certificate
The Tailscale connection
The Gateway token
Caddy itself
Missing chats or deleted workspaces

The proxy error was only a downstream symptom of the Gateway not reaching the ready state.

Why we created a backup first

Database migrations can change the format or structure of application data. Before making any change, we created a targeted backup containing:

OpenClaw configuration
The main state database
Memory databases
Migration artifacts

The backup was verified before continuing.

Existing larger backups were also preserved. No database was deleted, and no credentials were rotated.

This is an important safety rule:

Never remove a migration artifact before confirming that a recoverable backup exists.

The safe repair

The repair used OpenClaw’s supported doctor command against the same configuration and state directory:

openclaw doctor --fix

Because several containers shared the same OpenClaw state directory, those state-writing containers were temporarily stopped first. This prevented another process from changing the SQLite database during the repair.

After running the doctor command, the migration files were compared using checksums:

sha256sum main.sqlite main.sqlite.migrated

The files matched the previously archived copies. The stale migration sidecar was then moved to a dated archive instead of being deleted:

mv main.sqlite.migrated main.sqlite.migrated.archived-YYYYMMDD

This preserved the file for rollback or later investigation.

The Gateway was then restarted:

docker compose up -d openclaw-gateway

The other temporarily stopped containers were started again after the Gateway became healthy.

Verification after the repair

A successful container start was not enough. The following checks were performed.

Gateway status

docker inspect -f '{{.State.Running}} {{.RestartCount}}' openclaw-gateway

The Gateway remained running without restarting.

Local health endpoint

curl http://127.0.0.1:18789/healthz

Expected result:

{"ok":true,"status":"live"}

HTTPS dashboard

The dashboard was checked through the normal HTTPS route:

curl -I https://private-openclaw-domain.example/chat

The route returned HTTP 200.

TLS validation

The certificate was tested without disabling certificate verification. This confirmed that the HTTPS certificate was valid and trusted.

Reverse proxy configuration

The Caddy configuration was validated:

caddy validate --config /etc/caddy/Caddyfile

The configuration passed validation.

Browser and Tailscale access

The private domain was then opened from a browser connected to the correct Tailscale network.

A browser outside the tailnet could not reach the site. That failure was expected and did not indicate that the server was broken.

A separate AI provider problem

After the Gateway was repaired, another issue became visible: assistant replies could still fail even though the dashboard loaded correctly.

The logs showed provider-side failures such as:

Google model quota exhaustion
An OpenAI model returning 404 Model Not Found
OpenRouter insufficient credits
Another provider reporting insufficient balance

These are provider or billing problems, not Gateway connectivity problems.

This distinction matters:

Component	Result
HTTPS certificate	Healthy
Reverse proxy	Healthy
Gateway process	Healthy after repair
Dashboard route	Healthy
Tailscale access	Required for private access
AI provider availability	Depends on quota, billing, and model access

A healthy dashboard proves that the application is reachable. It does not prove that every configured model can answer requests.

Common mistakes to avoid

Changing DNS first

DNS changes do not repair a Gateway crash loop. Confirm that the domain resolves correctly before changing records.

Rotating the Gateway token unnecessarily

A token mismatch and a Gateway startup failure are different problems. Do not rotate credentials until authentication has been proven to be the failure.

Deleting the SQLite migration file

Deleting a migration artifact without a backup can make rollback difficult. Move it to a dated archive instead.

Changing ownership broadly

Permission problems should be fixed only on the exact paths that need correction. Broad ownership changes can affect unrelated applications and secrets.

Testing from the wrong network

A Tailscale-only service will not be reachable from a browser that is outside the tailnet. Always test private services from a confirmed Tailscale-connected device.

Assuming a 200 response proves everything works

A 200 response proves that the web route works. It does not prove WebSocket authentication, agent sessions, or model-provider availability.

A repeatable troubleshooting checklist

When OpenClaw returns 502 after an upgrade:

docker ps -a
docker logs --since 10m openclaw-gateway
docker inspect openclaw-gateway
curl http://127.0.0.1:18789/healthz

Then check:

Is the Gateway restarting?
Does the log mention migration failure?
Is a legacy SQLite sidecar present?
Are multiple containers writing to the same state directory?
Does a verified backup exist?
Does openclaw doctor --fix complete?
Does the Gateway remain stable after restart?
Does the proxy return HTTP 200?
Does normal TLS validation succeed?
Is the browser connected to the required private network?
Can the configured AI provider answer a test request?

Final lessons

The most important lesson is to separate the layers:

Network access determines whether the browser can reach the server.
TLS determines whether HTTPS is trusted.
The reverse proxy determines whether requests reach the Gateway.
The Gateway determines whether OpenClaw is ready.
The model provider determines whether the assistant can generate a reply.

In this incident, the visible 502 error was caused by a Gateway startup migration conflict. Once the stale migration artifact was safely archived and the supported repair completed, the Gateway and HTTPS routes returned to normal.

The remaining model errors were independent provider quota and model-access issues.

Safe upgrades depend on three habits:

Back up before migrations.
Read the Gateway logs before changing DNS or credentials.
Verify every layer separately after the upgrade.

Need help with an OpenClaw upgrade?

Visit OpenClaw911 for OpenClaw support resources, or contact us for help diagnosing a Gateway, proxy, migration, or private-network issue.