Skip to main content
Run these commands on the Engine host or from a CLI configured to connect to it:
doctor checks the node. diagnose explains one service, including health observations and remediation hints. Keep the structured error’s code and request_id when reporting a failure. Review logs before sharing them: your own application can print sensitive data.
  1. Check the host and port in the error. CLI remote settings override its local destination.
  2. Check the Engine service using the installation’s service manager and inspect its startup log; see Operations.
  3. On the Engine host, test curl --fail http://127.0.0.1:9321/api/health (use your configured port).
  4. If health works locally but remote access fails, check bind address, firewall and the connection method. Do not expose an unauthenticated Engine to fix connectivity.
A 401 or 403 is an authentication or permission failure, not a stopped process. Check the next section.
Check nerdit token whoami and nerdit capabilities --json. Confirm that the selected token has not expired, has the required role, and allows the service name. A submitter manages its own workloads; readonly cannot mutate them.Rotate a token before its expiry. An expired token cannot rotate itself: an administrator must issue a replacement. Do not paste tokens into an issue or agent transcript. See Security.
  1. Read nerdit logs my-app; the HTTP API also supports source=build to select build logs.
  2. Run nerdit diagnose my-app for the build failure, exit state or health failure.
  3. Confirm that the Dockerfile exists, its build dependencies can be downloaded, and the application listens on 0.0.0.0 at [deploy].port.
  4. Check the health path returns a successful response without login or redirects. Health-gated changes may leave the previous version serving; inspect last_deploy as well as current status.
  5. For a missing local model, serve it first; for a missing database or secret binding, fix the dependency before redeploying.
image_needs_privileges usually means an image’s entrypoint tried privileged work such as chown or changing user IDs. Use an image prepared to run without those operations; do not remove sandbox protections as a default fix.
A wait timeout is not a cancellation. Run nerdit services wait my-app --timeout 300, then inspect nerdit diagnose my-app. A newer deployment can supersede the generation you were waiting for. Check the current generation before retrying a write.
Run nerdit proxy status and nerdit routes. Confirm Caddy is available, the proxy is enabled, the listener port is free and the Engine has permission to bind it. Configure an unused unprivileged port if appropriate; do not stop another Caddy instance blindly.Then check DNS resolves the URL’s hostname to this node and the client trusts its CA. A path-mode app needs its /my-app/ prefix and may need framework base-path configuration. Subdomain mode requires service-specific DNS; bare-IP requests do not select a service.The HTTPS apex has no dashboard route unless dashboard_apex is enabled in path mode. The Engine’s own dashboard remains on the Engine port. See Networking and HTTPS.
If edge authentication references a missing or invalid secret, Nerdit withholds the proxy route. nerdit diagnose my-app reports edge_auth.secret_missing or edge_auth.invalid. Repair the named secret or declaration, then allow the proxy to reconcile.The container can remain running and reachable on loopback while the protected proxy route is withheld. Deleting an edge-auth block from local TOML alone does not necessarily remove its stored configuration; use the explicit configuration procedure in Security.
Check the domain’s cert_state, nerdit doctor and the Engine data directory’s caddy.log. With ACME enabled, the public DNS name must reach this node’s HTTP challenge listener from the internet. An ACME domain awaiting issuance does not silently fall back to an internal certificate.acme.disabled means public issuance is disabled on the node; acme.cert_pending means issuance has not completed. Follow Networking and HTTPS before retrying to avoid repeated failed certificate requests.
Look for [release] output in nerdit logs my-app and inspect nerdit diagnose my-app. A failed release command prevents the image swap; the previous deployment remains when one exists. Database changes made by the command are not rolled back.If the Engine restarted during the migration, treat its outcome as unknown. Inspect the data, repair it if necessary, and redeploy deliberately. See Backups and recovery.
For stdio, ensure the MCP client can find nerdit and that the MCP extra is installed in that same environment. For HTTP, verify /api/mcp is enabled, the Engine has an auth token and the client sends it. A missing HTTP mount normally returns 404.Host/Origin rejection, a missing Content-Length, or an oversized request are transport failures. A tool’s structured error can instead be a role, scope or ownership denial. Read MCP for both transports and the supported workflow.
Inspect nerdit disk and retention settings. Review the proposed effect of any garbage collection or purge against the resources you need to keep. A control-plane backup is not a logical database dump; select the recovery method in Backups and recovery.Do not edit the Engine database or swap state underneath a running Engine. Preserve the encrypted secrets and their separately held key when preparing recovery.
For App login, connection status and browser symptoms, start in App troubleshooting. For Engine bugs, see Development and support.