Substrate Diagnostics: Health Checks and Log Inspection

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.

substrate diagnose

Include the full output of substrate diagnose in any bug report you file.

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.

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.

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.

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.

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.

substrate diagnose

Attach the full output to every bug report. It gives maintainers environment, version, and health information in one snapshot.

substrate logs --errors

Attach error log output when the issue involves MCP tool failures or unexpected server behaviour.

Get Started

Concepts

Working with Agents

Authoring a Substrate

Operations

Substrate Diagnostics: Health Checks and Log Inspection

Health Check

Logs

Filing Feedback

substrate diagnose

substrate logs --errors

​Health Check

​Logs

​Filing Feedback

substrate diagnose

substrate logs --errors

Health Check

Logs

Filing Feedback