Diagnostics Bundle

When a problem spans layers — a panel error, a node that keeps disconnecting, and one misbehaving game server — collecting each log by hand is slow and easy to get wrong. The diagnostics bundle gathers everything for a time window into a single ZIP, with secret values redacted.

What the bundle contains

Path	Contents
`panel/logs.txt`	Panel container output for the window
`panel/environment.txt`	Effective panel configuration, secrets redacted
`panel/system-errors.json`	Persisted system errors for the window
`nodes/<nodeId>.log`	Node agent logs for the window
`servers/<serverId>/console.log`	Server console output for the window
`servers/<serverId>/.env`	The server’s `.env`, when present, secrets redacted
`manifest.json`	Machine-readable index, counts, and collection warnings
`README.txt`	Human-readable summary of the same

Every section is best-effort. A node that is offline, an agent that times out, or a panel deployed without a container runtime shows up as a warning in manifest.json instead of failing the whole export — read the warnings before concluding that an empty file means “nothing happened”. Collection is capped: 5,000 lines per node log, 8 MB per node and per server log, 20,000 server log rows, and 10,000 system errors (a cap adds a warning).

Prerequisites

admin.read on the panel (the bundle crosses tenant boundaries by design, so it is admin-only).
For the script: curl and network access to the panel — or directly to the backend when the frontend is down.

Export from the panel

Open Admin → System Errors.
Select Download diagnostics (not Export, which writes only the system errors as Markdown or JSON). The dialog is also titled Download diagnostics.
Pick a Time range: Last 1 hour, Last 6 hours, Last 24 hours (default), Last 7 days, Last 30 days, or Custom (From/To fields appear).
Under Nodes and Servers, leave Select all ticked to include everything, or untick it to choose specific entities. The server list has a search box.
Under Redaction, choose Standard — keep IPs and hostnames (default) or Strict — mask IPs and hostnames. Under Sections, leave the defaults (Panel logs, System errors, Node logs, Server logs, Config & .env) or untick what you do not need.
Select Download. The browser saves catalyst-diagnostics-<timestamp>.zip.

Export with the script

Use this when the panel UI is broken or you are working from a terminal. It calls the API directly, so it does not need the frontend.

bash collect-diagnostics.sh \
  --url https://panel.example.com \
  --api-key catalyst_your_admin_key \
  --hours 24

Without a checkout:

curl -fsSL https://raw.githubusercontent.com/catalystctl/catalyst/main/scripts/collect-diagnostics.sh \
  | bash -s -- --url https://panel.example.com --api-key catalyst_your_admin_key

Flags:

--hours N — window size, 1 to 720. Default 24.
--servers a,b / --nodes a,b — limit the export; pass none to omit.
--sections panel,errors,nodes,servers,env — include only what you need.
--redaction strict — also mask IPs and hostnames.
--out FILE — output path.
--cookie VALUE — raw Cookie header for a browser session, as an alternative to --api-key.
--timeout SECONDS — request timeout. Default 900.
-k — skip TLS verification for a self-signed certificate.

If the frontend is down but the backend port is reachable on the host, target the backend directly:

bash collect-diagnostics.sh --url http://localhost:3000 --api-key catalyst_your_admin_key

Equivalent raw API call

curl -fL \
  -H "Authorization: Bearer catalyst_your_admin_key" \
  "https://panel.example.com/api/admin/diagnostics/export?hours=24&redaction=standard" \
  -o catalyst-diagnostics.zip

Accepted query parameters: hours (default 24, clamped 1–720), from and to (ISO 8601; from overrides hours), nodes, servers (comma-separated IDs, or all / none), redaction (standard or strict), and sections (any of panel,errors,nodes,servers,env).

Host-level collection

The panel bundle cannot see the host filesystem: the install .env, Compose status, install logs, and container runtime health all live on the host, outside the backend container.

For that layer run the script that ships with the install directory, on the host. install.sh writes the stack to catalyst-docker/ in the directory you ran it from (usually ~/catalyst-docker):

cd ~/catalyst-docker
bash diagnose.sh --lines=500

Flags use =: --lines=N (default 500, --full raises it to 2000 and adds container inspect output), --out=DIR, --compose-dir=DIR, --mask-hosts (also mask IPs and domains), --full, and --skip-agent. It writes catalyst-diagnostics-<timestamp>/catalyst-diagnostics-<timestamp>.txt plus a matching .tar.gz — one redacted text bundle, not the ZIP the panel produces.

Attach both when the problem could be either the panel logic or the host configuration.

Redaction

standard (default) — secrets are replaced with [REDACTED]: passwords, tokens, API keys, license keys, cookies, and credentials inside connection URLs. IPs and hostnames are kept, because routing, CORS, and agent connectivity problems are much harder to diagnose without them.
strict — everything standard does, plus IPs become [IP_REDACTED] and hostnames [HOST_REDACTED].

Host masking is pattern-based: IP literals and hostnames ending in a well-known TLD (.com, .net, .io, .local, .internal, …). An unusual internal domain can survive strict mode.

The host-level diagnose.sh strips secrets by default too; --mask-hosts is its equivalent of strict mode.

Common errors — look up a code before exporting.
Panel issues — the export entry point lives in Admin → System Errors.