Troubleshooting

Check status, logs, and the health endpoint for your installation before changing settings. Installation and update commands are in Deployment.

[!IMPORTANT] Keep the existing data and secrets. Do not delete the database, remove volumes, or regenerate JWT_SECRET to fix a startup problem. Use Maintenance for backup and restore procedures.

For other symptoms, see networking, public content, login, storage, updates, or AI and newsletters.

Docker Run

Commands below use the container name orbitpage. Replace it if yours differs.

docker ps -a --filter name=orbitpage
docker logs --tail 100 orbitpage
docker port orbitpage
docker inspect orbitpage --format '{{json .Mounts}}'

Container exits or keeps restarting

Inspect its state and the startup error:

docker inspect orbitpage --format '{{json .State}}'
docker logs --tail 200 orbitpage

Check that the data mount is writable and has free space. An explicit JWT_SECRET must have at least 32 characters and must not be a placeholder. Without one, Docker generates and saves it in DATA_DIR/.jwt-secret (/app/data/.jwt-secret by default).

A port conflict can prevent Docker from starting the container before application logs exist. See Networking.

Data disappeared after recreation

Compare the current mount with the original deployment. The replacement must use the same volume or host directory at /app/data; the Docker Run example uses orbitpage-data.

docker volume ls
docker volume inspect orbitpage-data

If the original volume still exists, recreate the container with that mount and the original settings. An empty new volume starts a separate installation. If data was deleted, use Restore.

Environment or port changes are ignored

docker restart orbitpage keeps the container's existing settings. Recreate it after changing an environment file, port mapping, or mount. Keep the original data mount and secrets; use the Docker Run procedure.

Docker Compose

Run commands from the original project directory, using the same Compose file and project name as installation.

docker compose ps
docker compose logs --tail 100 orbitpage
docker compose port orbitpage 8080
docker compose ps -q orbitpage

Use the container ID from the last command to inspect its mount:

docker inspect CONTAINER_ID --format '{{json .Mounts}}'

After editing the configuration:

docker compose up -d --force-recreate orbitpage

Keep the existing storage path. For updates, use Docker Compose updates.

Linux installer

sudo orbitpage status
sudo orbitpage config
sudo orbitpage logs

logs follows output until you press Ctrl+C. config shows the saved address, port, image, and paths without printing secret values.

OrbitPage does not start

Read the application error, then check the protected environment file:

sudo test -s /etc/orbitpage/orbitpage.env
sudo stat -c '%a' /etc/orbitpage/orbitpage.env

The expected file mode is 600. Restore missing configuration from its backup. To repair an existing installer-managed deployment:

sudo orbitpage install

This preserves existing data and the secret. To use a newer installer, run sudo ./install.sh from an updated checkout.

Works locally but not on the LAN

Check the address and port with sudo orbitpage config. New installations use 0.0.0.0:8080; existing installations retain their saved address. To change a loopback-only installation, run from the current checkout:

sudo ORBITPAGE_BIND_ADDRESS=0.0.0.0 ./install.sh

If the address is already reachable, check the host firewall and network. See LAN and loopback.

Proxmox VE

Run these commands on the PVE host. Replace CTID with the OrbitPage LXC ID shown by pct list.

pct list
pct status CTID
pct config CTID
pct exec CTID -- orbitpage status
pct exec CTID -- orbitpage config
pct exec CTID -- orbitpage logs

If the guest is stopped, start it with pct start CTID. To find its address and check OrbitPage inside it:

pct exec CTID -- ip -4 addr
pct exec CTID -- curl -fsS --max-time 10 http://127.0.0.1:8080/health

Use the configured port if it differs.

For repair or listener changes, follow the Linux section inside the guest. Update commands are in Linux and Proxmox updates.

Container hosting platforms

Check these settings in the provider dashboard:

If deployment succeeds but OrbitPage is empty, inspect the attached volume before running setup again.

Source installation

See Run from source for the built application and Development for Vite with a separate backend.

Backend rejects JWT_SECRET

Source installations do not use the Docker entrypoint. Set a stable random secret in app/.env as described in the source guide. It must have at least 32 characters; placeholder values are rejected.

The temporary development fallback changes between processes. It is unsuitable for persistent sessions, TOTP, or encrypted credentials.

Environment settings or frontend changes are ignored

Start the backend from app/server:

node --env-file=../.env server.js

npm run start alone does not load app/.env. Host environment values take precedence over the file; saved dashboard overrides take precedence over both. See Configuration.

Restart after server changes. Rebuild from app/ with npm run build after frontend changes or changes to VITE_* variables. A published Docker image requires a new build to change its frontend variables.

Networking and HTTPS

Check health directly before testing the public domain. Run on the Docker/Linux host, or inside the Proxmox guest:

curl -fsS --max-time 10 http://127.0.0.1:8080/health

A successful response contains "status":"ok" and the running version. Use the actual port; for a remote check, replace 127.0.0.1 with the device's LAN address.

Exclude API, dashboard, localized dashboard, and health responses from proxy caching. With a URL mount path, include it in PUBLIC_SITE_URL and set BASE_PATH. See Reverse proxy and HTTPS.

Public page and content

See Publishing and QR and SEO and indexing.

Login and setup

Login stops working after restart

Check whether the data mount or JWT_SECRET changed. A changed secret invalidates sessions and can make TOTP, AI keys, or SMTP credentials unreadable when their encryption uses that secret.

Restore the original secret from its protected backup, apply it through the original deployment method, and sign in again. For a lost password or authenticator, use Administrator recovery.

Setup asks for a token

If REQUIRE_SETUP_TOKEN is enabled, read the token on the host and enter it in the setup wizard:

Use the actual container name or data path if customized. Keep the token private. See Setup-token configuration.

Storage and uploads

For disk or SQLite errors, check the data path. On Linux, check disk space and available inodes:

df -h
df -i

For Docker storage usage, run docker system df. For Linux installations, sudo du -sh /var/lib/orbitpage shows data usage. For manual bind mounts, use the actual directory shown by docker inspect.

Check that the mount is writable, with ownership and permissions suitable for the application process. Back up before database repair; keep SQLite sidecars and hidden secret/configuration files with the database.

Updates

Image pull or dashboard installation fails

Use paoloronco/orbitpage:latest or ghcr.io/paoloronco/orbitpage:latest. Pinned versions use X.Y.Z, without a leading v. If a pull fails, check the exact tag, registry connectivity, and Docker disk space.

Dashboard installation needs the host update service. Terminal instructions are expected for source deployments, custom/pinned images, or hosts without the service.

For the default container name, inspect the service on the Docker/Linux host:

sudo systemctl status orbitpage-updates-orbitpage.service
sudo journalctl -u orbitpage-updates-orbitpage.service -n 100 --no-pager

Replace the final orbitpage in the service name if using a custom container name. In Proxmox, run these checks inside the guest.

Update result is unclear

Check status, logs, and /health before retrying. Compare the returned version with the expected release; also verify dashboard login, public content, and uploaded media.

Host-updater backups are retained under /var/backups/orbitpage. Inspect them and the service error before retrying. Use Deployment for update commands and Maintenance for rollback.

AI and newsletters

See AI assistant and Newsletters.

Report a problem

Include the installation method, OrbitPage version, relevant error, and steps to reproduce. For networking issues, include the direct /health result and the public HTTP status.

Use the status/log commands in your installation's section. For Docker, also collect the image name with docker inspect orbitpage --format '{{.Config.Image}}'; for Compose, use its container ID.

Before sharing, remove secrets, tokens, cookies, SMTP credentials, and private account/page data. Do not post complete environment files or unredacted docker inspect / docker compose config output.