Troubleshooting
Start with computerctl doctor and confirm the broker, user session and configuration you intended to use. Read the returned error as a boundary to investigate, not as an invitation to escalate privileges.
The client cannot reach the broker
Section titled “The client cannot reach the broker”The CLI and MCP frontend do not replace the daemon. Confirm that the broker is running, that the client uses its intended socket, and that both processes belong to the same login user and runtime. Do not change a protected socket to world-writable or run the daemon as root to make a connection succeed.
Discovery works, but an operation is denied
Section titled “Discovery works, but an operation is denied”Discovery is not authorization. Inspect the command descriptor, current owner policy and exact application or filesystem scope. Enabling a provider does not add grants. An unavailable backend and a denied capability are different problems.
The operation needs consent
Section titled “The operation needs consent”Broker confirmation and compositor portal consent are separate. A user service cannot answer an operator prompt. Follow the permission guide’s foreground approval path when it is appropriate; do not add an automatic confirmation flag or weaken the risk classification.
A reference is stale or ambiguous
Section titled “A reference is stale or ambiguous”Discover the target again in the same session. Review all candidates when a selector is ambiguous. Never assume that the reused object ID identifies the same control. A stale target is not a reason to fall back to coordinates.
An application driver will not start
Section titled “An application driver will not start”Check its exact application version, pinned executable digest, protected manifest, required named mounts and resource bounds. Read its own README. The persistent host intentionally refuses unsandboxed execution; a missing isolation prerequisite must not be hidden with an unrestricted fallback.
A mutation timed out
Section titled “A mutation timed out”A timeout does not prove that no side effect occurred. Inspect the application state through a safe observation before deciding what to do next. Do not automatically repeat a non-idempotent operation.
Reporting a reproducible issue
Section titled “Reporting a reproducible issue”Include the source revision, tool versions, high-level configuration and minimal synthetic fixture. Remove credentials, session tickets, private documents, clipboard content and screenshots of unrelated applications. Follow the repository security policy for sensitive reports.
These diagnostics follow the architecture, permissions and driver contract reviewed 22 September 2026.