Skip to content

UI issues after an update

After a GUI update, the interface looks broken — white screen, old version, missing buttons, endless loading. In the vast majority of cases this isn't a bug in the update itself, but an intermediate state or a cached old frontend build.

The "Vesana is starting …" splash

During an update's restart phase, the interface is genuinely unreachable for a short time — the container is recreated, migrations run, the stack comes back up. An overlay deliberately bridges this gap with a "Vesana is starting …" splash and specifically checks whether the new version is really responding, not just any response. That prevents a premature "done" state while the old version is still running in the background.

This is normal and needs no action — just wait for the splash to disappear on its own. With very large migrations (lots of historical data) this can take longer than usual.

If the splash stays up unusually long (more than a few minutes): see Updates → Progress display and, if needed, Update doesn't run through.

Try a hard reload first

The most common "UI still shows old buttons/is missing a feature" case after a successful update is simply a cached old frontend build in the browser. Before any deeper diagnosis:

  • Chrome/Firefox/Edge: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS)
  • If that's not enough: clear the browser cache for the domain completely (dev tools → Application/Storage → clear cache; or browser settings → cached images and files)
  • For very stubborn cases: open an incognito/private window and test there — instantly shows whether it's the local cache

A normal reload (F5) often only reloads the HTML shell while bundled JS/CSS assets are still served from the browser cache — hence explicitly a hard reload, not just a reload.

After a domain/URL change

If the server URL was changed shortly before the problem occurred (see Changing the server URL later), the browser may still cache API calls against the old address. A hard reload helps here too; if the problem persists, check directly in the dev tools (network tab) which URL the frontend is actually sending requests to.

Did the container actually restart?

If the UI still shows the old version number after a hard reload (visible e.g. at the bottom of the admin area or in the update history), the update didn't land at the container level — independent of the browser. Check:

cd /opt/vesana
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs frontend --tail 100

Is the frontend container still running the old image, or was it never recreated? That points to a stuck or failed update — see Update doesn't run through.

nginx shows a mixed version

Rare: the API container is already on the new version, but nginx is still serving cached old static assets. A docker compose restart nginx (or, with a split setup: the respective reverse proxy) forces fresh assets to be served.

Checklist

  1. Wait out the splash, don't treat it as a fault immediately
  2. Hard reload (Ctrl/Cmd+Shift+R)
  3. Clear the browser cache completely, test in an incognito window if needed
  4. Compare the version number in the UI against the actual container state (docker compose ps, docker compose logs)
  5. Only then assume a real update failure

Next