Reading the engine log

The engine log is the first place to look for anything that is not a network problem. Messages are prefixed by scope, and a !! marks a warning or an error.

follow the log

# systemd sudo journalctl -u lf-engine -f sudo journalctl -u lf-engine -n 200 --no-pager

pm2

sudo env "PATH=$PATH" pm2 logs lockflare --lines 200

Scopes

Scope	Covers
`boot` / `[FETCH]`	Licence, reaching the control plane, fetching and decrypting builds.
`app` / `[TENANT]`	Starting and running your application.
`local` / `[LOCAL]`	Storing an encrypted build on this server, free-plan storage.
`enclave` / `[ENCLAVE]`	Sealing and unsealing.
`fwd`	Node only. Forwarding a request between workers.
`[CGROUP]`	.NET only. Per-application memory and process limits.

Startup and licensing

Message	What it means
`LICENSE not set in .env` `[INTERPRETER] LICENSE not set in environment`	No licence key. Run the engine by hand once to be prompted, or add `LICENSE=` to `.env`. The .NET engine exits immediately.
`[FETCH] bootstrap rejected (bad license/IP?)`	The licence does not match this server’s address. Almost always a mistyped IP at registration, or a machine behind NAT whose public address differs. Re-register with the correct address — a licence cannot be repointed.
`bootstrap failed — no data from Unity. Set LICENSE in .env and restart.`	Every attempt to reach the control plane failed. Check outbound connectivity from the server first, then the licence.
`connecting to Unity (attempt 2/…)` · `retrying in 3s`	Normal transient retry. Only a concern if it never succeeds.
`Failed to decrypt bundle from Unity`	The configuration payload arrived but would not decrypt. Usually a licence that has been rotated or replaced — re-register the server.

Fetching builds

Message	What it means
`[FETCH] R2 decrypt failed (key/AAD/tag)`	The artifact did not authenticate. The build is bound to its project and content hash, so this is a mismatch rather than a corrupt download. Push again.
`[FETCH] no local copy and no download URL`	The server was told to use a locally-stored build that is not present. Push again to restore it.
`[FETCH] no DLLs in app zip`	.NET only. The published output contained no assemblies — usually `dotnet publish` pointed at the wrong folder.
`[FETCH] R2 blob too large`	The artifact exceeded the size ceiling. Check for a build output that has picked up something it should not, such as a `node_modules` or a source-map bundle.
`stored copy unusable, discarding and refetching`	Self-healing. The local copy failed verification and the engine is fetching a fresh one.

Your application

Message	What it means
`missing npm packages on the fleet` `fix: npm install …`	Node only. A bare `require()` for something outside the shared package set. The engine names the packages — install them on the server and restart, or bundle them into the artifact. See Node runtime limitations.
`start failed — will retry on request (backoff)`	Your application threw while starting. The message that follows is your own error. The engine keeps the previous healthy instance serving and retries.
`could not initialize`	The application failed before it produced a handler. Check the starting file is the one that actually launches your server.
`forwarded but handler not ready (async .listen pending)`	Node only. A request arrived before the application finished starting. Harmless in isolation; persistent means something in startup never resolves.
`cluster.fork() beyond licensed N worker(s) ignored`	Your application asked for more workers than the server is licensed for. Not an error — the extra forks are ignored. Add cores if you want them.
`forwarded body exceeded … — 413`	An upload exceeded the forwarding ceiling. Raise `LF_FORWARD_MAX_BODY` if the request is legitimate.
`[TENANT] refusing restart: previous generation could not be terminated`	.NET only. The prior instance’s cgroup would not drain, so the engine will not start a second copy against a stale limit. Restart the engine.

Enclave

Message	What it means
`HMAC verification failed`	A seal or unseal command failed authentication. Replayed or stale control traffic is rejected by design — retry from Cipher.
`PARTIAL UNSEAL — 2/3 restored; enclave file RETAINED for retry`	Act on this. Some accounts were restored and some were not. The enclave file is kept deliberately so the unseal can be retried — retry it before assuming the server is open.
`Failed to report status to Unity after N attempts`	The seal state changed but Cipher was not told. The server is correct; the dashboard may show a stale seal status until the next report.
`breaking stale enclave lock (previous holder likely crashed)`	Recovery from an interrupted seal operation. Informational.
`accepted the LEGACY fleet-wide key`	Something authenticated with an older credential. Working, but worth migrating that caller to the per-server credential.

On a sealed server you cannot read these logs — there is no login. If a sealed server has gone quiet and does not recover on its own, rebuild it. See Understanding a LockFlare server.

A server will not come online A push fails or does nothing