Skip to content
SHC Docs

Troubleshooting

First-stop index for when something isn’t working. Look up your symptom below; each entry points to the relevant page, source code, or error code.

For deep operational topics (upgrades, disaster recovery, backups), see ../operations/.

For the full list of every error code SHC can emit, see ../../reference/errors.md: 508 codes across 27 modules, auto-generated from source.

interactive: drag or click to explore
  • Backup creation fails → Common backup failures
  • Restore doesn’t find the target stack → the stack is restored under the (tenant, stack, environment) tuple; check you’re targeting the right environment
  • “Converter failed” during backup → X500908HKFAIL: run the converter manually to reproduce; see backup-restore flow
  • Vault locked, writes failing → Vault: Unlocking on daemon start
  • {{ vars.password }} renders as literal ref+vault://... → the vault couldn’t resolve the reference. Check scope, provider health, and Vault: Failure modes
  • Restored backup has undecryptable secrets → master password from the source cluster differs; rotate (shc vault rotate)
  • shc events disconnects / gaps → SSE troubleshooting
  • No events at all → check shc status: a stuck queue shows tasks piling up without draining. See Observability
  • Audit log empty → verify the actor had a populated Ctx; unauthenticated requests via localhost UDS skip audit by design; see security: audit trail
  • “permission denied” on a valid-looking action → X403900NOPERM. See security: authorization for how scopes + resources match.
  • “tenant not found” when you’re sure it exists → you’re in the wrong tenant. Check shc ctx / SHC_TENANT.

Modules register self-checks with the doctor framework; shc doctor run sweeps them all. Diagnoses only by default; repairs need an explicit --fix:

Terminal window
shc doctor run # run every registered diagnosis
shc doctor run --category storage # only one module's diagnoses
shc doctor run --fix # also apply prescriptions for fixable findings
shc doctor ls # list registered diagnoses (and their categories)

Other high-signal commands:

Terminal window
shc node ls # cluster membership + leader
shc cluster status # node counts, voter/quorum state, leader
shc cluster mesh diagnose # this node probes peer internal APIs over mesh0
shc events # live lifecycle event stream
shc events --audit # recent audited actions
shc job history # recent hook / integration job runs
shc logs --follow # follow container logs
shc hud # live TUI overview

  • Look up the error code. Error reference has every one with source location.
  • Check the flow doc. The flows pages trace each major pipeline step-by-step with file/line pointers, so you can see exactly where you’re stuck.
  • Read the source. SHC’s architecture docs cite source files and line numbers directly. Clone the repo, search for the error code, read the raising function.