# Troubleshooting Troubleshooting in One starts from the exact failing subject and preserves the evidence needed to explain it. Do not begin by deleting `.one/`, regenerating a lock, widening authority, switching providers, or retrying a possibly dispatched effect. ## Start with disposition and definition ```console one status one inspect one inspect command: ``` Human diagnostics lead with the failed user action, owner stage, source span, smallest conflict, and safe next action. Machine output retains the diagnostic code and schema revision, exact subjects, structured details, source maps, proof obligation, and evidence references. Follow definition links from a clause, package, trait, profile, command, provider, plan field, artifact, observation, or receipt to its exact defining package and revision. When a snapshot is stale or its defining evidence is unavailable, navigation says so rather than resolving against current but different content. ## Diagnose by failure class | Result | Meaning | Safe next action | | --- | --- | --- | | Invalid source or type | Current authored bytes do not form an accepted owner value | Fix the exact source diagnostic and rerun the owning check | | Unresolved dependency | Source, lock, package, resolver, or tool coordinate is absent or ambiguous | Inspect candidates; review `one sync` rather than accepting a guessed name | | Incompatible change | The requested revision violates a compatibility obligation | Inspect impacted roots and author an explicit evolution plan | | `Unsupported` | No selected implementation provides the requested semantics | Add or select a real implementation; do not simulate success | | `Unsatisfied` | Candidates exist but none meet all hard requirements | Inspect rejected alternatives and change the requirement or eligible realization explicitly | | Missing evidence | A claim cannot currently be trusted for this scope | Acquire or refresh the exact required evidence | | Denied or pending | Policy rejected the action or required approval is absent | Request the exact approval; do not widen the subject or grant | | Stale | Source, lock, observation, plan, or transaction base changed | Refresh, review the new delta, and produce a new exact record | | Outcome unknown | Dispatch may have occurred but no terminal proof exists | Reconcile the existing operation identity; never issue a fresh blind retry | | Internal defect | One violated its own contract | Preserve the bounded diagnostic reference and relevant evidence for support | Partial results retain the successful subjects and independent failures. A batch does not collapse them into one generic exit status. ## Inspect locks, plans, and releases Useful questions include: ```console one inspect why one inspect one inspect one observe ``` Check that source revisions match the accepted lock, provider evidence is admitted and fresh, the Build consumed the selected plan, approval and grant subjects match, and observed postconditions belong to the same release and fence. A healthy process or provider response cannot substitute for a missing owner receipt. ## Handle an interrupted effect If a command ended after possible dispatch, retain its operation identity: ```console one reconcile operation: ``` Reconciliation queries journal, fence, provider, receipt, and observation state. It may conclude committed, not dispatched, safely retryable, compensatable, or still unknown. Closing a terminal, cancelling a future, losing the daemon, or timing out does not prove rollback. ## Use debug access deliberately ```console one debug ``` A debug session is capability-scoped, time-bounded, attributable, and separate from production authority. Its observations do not silently become semantic truth or release evidence. Secret values remain redacted unless the exact debug capability explicitly authorizes their protected boundary. For daemon-backed clients, verify the explicit endpoint with `one daemon status`. Stale daemon diagnostics may be shown as stale but cannot authorize an edit, Build, plan, or release. Direct and daemon-backed commands resolve the same project and owner contracts. ## Clean only reconstructible state `one clean` removes reconstructible projections and work directories. `one gc` collects unreachable cache/CAS objects while retaining everything reachable from locks, artifacts, plans, journals, evidence, snapshots, and sessions. `one reset local` requires an explicit disposition for durable data, unresolved effects, and protected evidence. Corrupt caches may be evicted. Corrupt locks, plans, grants, journals, and evidence fail closed and use their owner's restore or recovery operation; they must not be treated as disposable cache. See the [failure model](/one/reference/failure-model), [recovery and continuity](/one/lifecycle/recovery), and [inspect and operate](/one/lifecycle/inspect-operate).