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

# Substrate Diagnostics: Health Checks and Log Inspection

> How to use substrate diagnose and substrate logs to inspect installation health, surface errors from long-running processes, and file bug reports.

When something goes wrong with Substrate, two commands give you a clear picture before you start guessing: `substrate diagnose` runs a suite of health probes across your environment and installation, and `substrate logs` surfaces warnings and errors written by the long-lived processes. Both are designed to be useful exactly when things are broken.

## Health Check

`substrate diagnose` prints environment and substrate health, and exits non-zero if it finds a problem. Every probe is individually wrapped, so a missing or malformed `config.json` produces a diagnostic line rather than a crash. It also reports where a live `substrate serve` is bound, reading `.substrate/serve.json`, and whether the installed agent skill has drifted from the binary.

```sh theme={null}
substrate diagnose
```

<Note>
  Include the full output of `substrate diagnose` in any bug report you file.
</Note>

The command runs the following probes in order:

| Probe           | Tells you                                                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Environment** | Node version, platform, binary's version and schema version.                                                                   |
| **Substrate**   | Whether `.substrate/` exists, and whether `config.json` parses.                                                                |
| **Boards**      | Whether the substrate loads, and how many boards, policies, and members.                                                       |
| **Database**    | Whether `data.sqlite` opens, and its current schema version.                                                                   |
| **Server**      | Whether a `serve` is live and which port it bound, read from `.substrate/serve.json`, falling back to probing ports 7475–7499. |
| **Skill**       | Whether the installed agent skill has drifted from this binary.                                                                |
| **Log**         | Recent error activity from `.substrate/logs/substrate.log`.                                                                    |

## Logs

The long-lived processes — `substrate mcp` and `substrate serve` — record warnings and errors to `.substrate/logs/substrate.log`. This file is gitignored and local-only.

```sh theme={null}
substrate logs              # last 50 lines
substrate logs -n 200       # last 200 lines
substrate logs --errors     # errors only
```

Log reading is rotation-aware, so `-n` is honoured correctly even across a rotation boundary.

Two different empty states carry different meanings:

| Output                 | Meaning                                           |
| ---------------------- | ------------------------------------------------- |
| Log file is absent     | No `mcp` or `serve` process has ever logged here. |
| Present, but no errors | It ran cleanly.                                   |

<Warning>
  Only `mcp` and `serve` write to the log. Short-lived commands do not, so running `substrate logs` after a failed `substrate import` tells you nothing about that import failure.
</Warning>

<Tip>
  An agent's handled tool errors land in this log too. Use `substrate logs --errors` to review an agent's own error trail. Routine gate blocks and stale-version retries are excluded deliberately — they are normal operation, not faults.
</Tip>

## Filing Feedback

The `submit_feedback` MCP tool takes a `title` and `body` and returns a prefilled GitHub issue URL for `42pe/substrate`. Nothing is sent automatically — there is no network call, no credentials are needed, and nothing is stored. A human opens the returned URL and submits the issue.

<CardGroup cols={2}>
  <Card title="substrate diagnose" icon="stethoscope">
    Attach the full output to every bug report. It gives maintainers environment, version, and health information in one snapshot.
  </Card>

  <Card title="substrate logs --errors" icon="file-lines">
    Attach error log output when the issue involves MCP tool failures or unexpected server behaviour.
  </Card>
</CardGroup>