> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nerdit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot the Engine

> Start with the symptom, collect the relevant diagnostics, and apply a targeted fix.

Run these commands on the Engine host or from a CLI configured to connect to it:

```bash theme={null}
nerdit doctor
nerdit capabilities
nerdit diagnose my-app
nerdit logs my-app
```

`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.

<AccordionGroup>
  <Accordion title="The CLI cannot reach the Engine">
    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](/engine/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.
  </Accordion>

  <Accordion title="Requests return 401 or 403">
    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](/engine/security).
  </Accordion>

  <Accordion title="The build fails or never reaches healthy">
    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.
  </Accordion>

  <Accordion title="The CLI timed out, but the application is running">
    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.
  </Accordion>

  <Accordion title="The service works on loopback but its HTTPS URL fails">
    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](/engine/networking).
  </Accordion>

  <Accordion title="A protected application returns 404">
    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](/engine/security).
  </Accordion>

  <Accordion title="A public domain has no valid certificate">
    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](/engine/networking) before retrying to avoid repeated failed certificate requests.
  </Accordion>

  <Accordion title="A deployment migration failed">
    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](/engine/backup-recovery).
  </Accordion>

  <Accordion title="MCP cannot connect or a tool is denied">
    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](/engine/mcp) for both transports and the supported workflow.
  </Accordion>

  <Accordion title="Disk usage is growing or a restore is needed">
    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](/engine/backup-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.
  </Accordion>
</AccordionGroup>

For App login, connection status and browser symptoms, start in [App troubleshooting](/app/troubleshooting). For Engine bugs, see [Development and support](/engine/development).