Troubleshooting

What the common failures look like and where to look first.

See what is unhealthy

make status

make logs s=portal-api

The images will not pull

They are private. Sign in with a GitHub token that has read:packages:

docker login ghcr.io

If the version in .env was never published, build from source with ./install.sh --build.

The Portal API exits at once

It does not start without PLATFORMX_JWT_SIGNING_KEY. Run ./install.sh again; it generates the key when it is empty.

Signing in succeeds, then the portal signs out

The refresh cookie is Secure. It is dropped when the portal is reached over plain HTTP or through a certificate the browser does not trust. Use HTTPS, and on localhost trust the proxy’s local authority.

A setting changed in the database has no effect

The services cache tenant settings at boot. Run make restart.

A widget does not appear on a page

Read the Public API’s log before anything else:

make logs s=public-api

A widget that throws is logged as Failed To execute widget <code> and left out of the response; the rest of the page is served normally.

Uploads fail at the last step

Uploads need blob storage. Check that azurite is healthy, or that the Azure settings in .env are right.