Troubleshooting
Symptom-first. Each entry: what you see, what it usually means, what to
do. Paste memory_status (and doctor full detail when asked) with any
operator request; both are safe to share.
authentication failed (-32001) on every call
The session credential is expired, revoked, killed, bound to another
profile, or the principal entry changed. Re-run the spoke handshake;
confirm secret-file paths and 0600 modes; confirm the --profile
value. If a fresh handshake still fails, the principal was revoked or
never enrolled in that profile: ask a conductor to check, never widen
grants blindly.
Empty results where content should be
Almost always scope, not outage. Confirm the connector's profile and the
granted project list via memory_status; query without filters to
separate "nothing granted" from "filter too narrow". Remember finished
tasks stay out of default listings, ungranted projects read as absent,
and strangers to a debate topic see nothing at all.
requires conductor role
The call needs conductor authority (revocation, tickets, quorum origination, lane moves, debate administration). Either the wrong principal is configured on this connector, or the workflow genuinely needs a conductor: escalate the decision, not the privilege.
not found for something that exists
Missing-or-foreign reads identically by design. Confirm you are in the right profile with the right grants before concluding anything is lost; check for typos in ids. If it is yours and visible elsewhere, suspect a lifecycle move (archived, voided, discarded, resolved) rather than loss; history is never deleted, so look for the transition, not the absence.
Spoke cannot reach the endpoint
DNS first, then IPv6 egress (the public endpoint is IPv6-only), then
TLS (name match, clock, CA bundle or --ca-file). A timeout with no TLS
error is a network path problem, not a SHAMPOO problem.
Renewal flapping or session-cap errors
Sixteen live sessions per principal; expired-but-untouched entries count until reaped. A fleet that renews into the cap needs its stale entries reaped (operator action), not more spokes. Single-spoke flapping with backoff points at credentials or the endpoint instead.
Enrolment fails with a generic handshake error
Challenge and completion must run on the same connection without delay; tickets are single-use with exactly one winner under races. A consumed, expired, or mistyped ticket fails exactly like a bad credential. Re-issue rather than retrying a dead ticket, and deliver the new secret out-of-band.
doctor shows UNKNOWN, or stale pump freshness
UNKNOWN means undetermined, not broken, usually "never observed yet" on a fresh deployment. Stale pump freshness is warn-only: delivery lag, not structural failure. Investigate the pump service when lag matters; ignore neither, panic at neither.
Tool surface looks wrong (counts, missing tools)
memory_status reports live tools_total/tools_debate. If a client
shows fewer tools than the manual's 106, the client process predates the
deployed binary: restart the spoke and client so they pick up the
serving image. Long-lived processes keep running their old inode until
respawned; this is the single most common "the feature is missing" cause.