Known Issues — Environment & Device Problems

Not software defects — caused by the customer's network, host machine, or device configuration

ℹ️

This page is a running log of issues that come up on customer installations where the root cause is the local environment (firewall, DNS, Docker Desktop, browser, device clock, LAN configuration, etc.) rather than a defect in SeaVesselManager itself. Each article documents the symptom, how we confirmed the cause, and the fix, so support can link to it directly instead of re-diagnosing from scratch every time.

Each article is tagged:

🖥️ Environment / Device — confirmed cause is outside the application (network, OS, hardware, browser).

If an issue turns out to be an actual application bug after investigation, it is moved out of this log and filed in the engineering issue tracker instead — this page only lists confirmed non-bug issues.

"Could not reach backend" after a fresh Docker install

🖥️ Environment / Device Reported on: self-hosted Docker install

Symptom

Right after a fresh Docker installation, the frontend loads at http://<server-ip>:3000, but pages that call the API (e.g. Admin → Settings → License) show:

⚠️

"Could not reach backend — make sure the server is running and the migration has been applied."

Why this is a device/environment issue, not a bug

This message is shown by the frontend any time its request to the backend API fails outright (network error, not an application error response). On a fresh install this is almost always one of:

The backend container is still starting, crash-looping, or failed to apply migrations.
Port 4001 is blocked by the host's firewall while port 3000 is open, so the browser can load the UI but can't reach the API.
.env is missing a required secret (JWT_SECRET, JWT_REFRESH_SECRET, POSTGRES_PASSWORD), which makes the backend refuse to start by design (see Security rules — no fallback secrets).
Postgres data volume didn't finish initializing before the backend's first connection attempt.

None of these are caused by application code — they are host/network configuration on the customer's machine.

Diagnostic steps

Run these on the machine hosting the Docker install (inside the docker/server/ folder, or wherever docker-compose.yml lives):

Check container health

docker compose ps

Look at the svm-server-backend row. It should say healthy. restarting or unhealthy means it's crash-looping.

Read the backend logs

docker compose logs backend --tail=100

Look for:

FATAL — missing JWT_SECRET / JWT_REFRESH_SECRET in .env
Postgres connection errors (ECONNREFUSED, auth failed)
Migration errors (QueryFailedError, a named migration that failed)
A clean boot ends with Nest application successfully started and ✅ [CORS] CORS enabled

Check Postgres came up cleanly

docker compose logs postgres --tail=50

On first boot this runs the baseline schema (01-complete-schema.sql) and migration markers. Errors here block the backend from ever connecting.

Confirm the API responds locally on the host

curl http://localhost:4001/api/v1/health

Run this on the Docker host itself, not from a browser on another device. If this fails locally, it's a startup problem (go back to step 2) — not a network/firewall problem.

Check firewall / port forwarding if step 4 works locally but not from a browser

Windows: allow inbound connections on ports 3000 and 4001 in Windows Defender Firewall.
Linux: sudo ufw allow 3000/tcp && sudo ufw allow 4001/tcp
Cloud/VPS: check the security group / network ACL allows inbound 4001, not just 3000.

The web app is served on :3000, but the browser calls the API directly on :4001 when there's no reverse proxy in front — both ports must be reachable from the client device.

Fix

✅

In every case seen so far, the fix was on the customer's machine: opening port 4001 in the firewall, filling in a missing secret in .env before first boot, or waiting for Postgres to finish initializing before hitting the app. No backend/frontend code changes were required.

If docker compose logs backend shows the app started successfully and curl on the host works, but the browser on another device still can't reach it, treat it purely as a network/firewall issue on that device or the LAN, not the application.

Related: General Troubleshooting guide · Still stuck? support@seavesselmanager.com