Dialog — systemg

Dialog

When something fails, sysg answers like a compiler: what happened, the evidence it captured while it happened, and the exact next commands to run. Every user-facing failure is a structured diagnostic with a stable error code.

error[SG0104]: service `gamecast_api` failed to become healthy

  the health check against http://127.0.0.1:8080/api/v1/health ran but reported
  the service is not healthy after 10 attempts over 45s (configured total
  readiness budget: 45s)
  the process is not running — it exited before it could become healthy

  last output from `gamecast_api`:
  │ Error: error returned from database: password authentication failed for user "postgres"

  help:
    view logs     sysg logs -s gamecast_api -p gamecast-api-dev
    check status  sysg status -p gamecast-api-dev
    docs          https://sysg.dev/how-it-works/dialog/codes#sg0104

Anatomy

Every diagnostic has the same shape:

Part	What it tells you
error[`SG0104`]	Severity and a stable code you can search or look up
Title	One sentence stating what happened
`-->` location	The config file and key the problem originates from, when known
Notes	Plain-sentence facts sysg observed (exit codes, timing, liveness)
Evidence	Output sysg captured — usually your service's own last log lines
`help:`	Runnable commands and a docs link for this exact code

Colors

On a terminal, diagnostics are colored: red for errors, yellow for warnings, cyan for notes and locations, green for the help section, bold for runnable commands, and underlined blue for docs links. Piped or redirected output is plain text with no escape codes, and NO_COLOR is respected.

gamecast — zsh

➜  gamecast sysg start -c sysg.api.yaml --daemonize
error[SG0104]: service gamecast_api failed to become healthy

  the health check against http://127.0.0.1:8080/api/v1/health ran but reported
  the service is not healthy after 10 attempts over 45s (configured total
  readiness budget: 45s)
  the process is not running — it exited before it could become healthy

  last output from `gamecast_api`:
  │ Error: error returned from database: password authentication failed for user "postgres"
  │ Caused by:
  │     password authentication failed for user "postgres"

  help:
    view logs     sysg logs -s gamecast_api -p gamecast-api-dev
    check status  sysg status -p gamecast-api-dev
    docs          https://sysg.dev/how-it-works/dialog/codes#sg0104

This is the real SG0104 renderer output — the same bytes diag.rs writes to a tty, shown here with its colors.

Error codes

Every diagnostic carries a stable SGXXXX code you can search, script against, or look up. The full list, with a description of each, lives on the Codes page — every code has its own anchor (e.g. SG0104) that the diagnostic's docs link points at.

Where evidence comes from

sysg already captures every service's stdout and stderr (see Logs). Diagnostics quote the last lines of that capture at the moment of failure, so the reason a service died — a bad database password, a port conflict, a missing binary — arrives inside the error itself instead of behind a sysg logs round-trip.

← Start vs Spawn Codes →