Troubleshooting

Start with the exact release version, the command output, and any local validation evidence. Avoid mixing assets from latest and a versioned release directory.

For divergent prompts, templates, manifests, materialized output, or partially upgraded workspace metadata, use Upgrade prompt and template customizations before authorizing force or migration.

For legacy planning roots, interrupted repository transactions, or write-lock evidence, start with Migrate an existing workspace and Transaction and operational recovery. Do not manually rearrange .day-shift/ while diagnosis is incomplete.

The GUI will not open

Run day-shift --version, day-shift serve --help, and day-shift doctor --runtime-only --format json. Verify that the selected release includes GUI assets and meets its Node.js prerequisite. Start day-shift serve --open from the intended project, keep that terminal running, and use its printed local address. If a requested port is busy, stop the server you own or choose another port with --port; do not terminate an unknown process.

After a restart, use the current project link or new startup URL. Preserve unsaved text before reloading. For project-chat context, stale operation identities, grouped saves or undo conflicts, see Project chat and planning updates. Preserve local conversation and transaction evidence until the canonical save outcome is known. You can continue with the terminal workflows while diagnosing a browser issue.

Inspect failures caught during GUI use

Open Settings → Diagnostics, then Refresh diagnostics. The view groups caught browser, runtime, provider and watcher failures by cause, with occurrence counts, first/last seen times, version, action and available request/stack details. Start with This session, or select All retained sessions or Errors only and use Find failures. Copy report and Export report include the selected filter; the on-screen list shows at most 200 groups.

Diagnostics are local to the project at .day-shift/state/private/diagnostics/. They are not uploaded automatically. Records avoid request bodies, documents and chat messages; the collector redacts recognized credentials and sensitive paths from error metadata. Review exported text before sharing it. Routine request cancellations and expected conflicts are excluded. This is a record of caught failures, not proof that every bug, crash or failed check was detected. Validation outcomes remain in Validation evidence.

Storage retains up to 10 MB (10,000,000 bytes) across runtime sessions and removes the oldest segments as new records arrive. There is no age-based expiration. A runtime restart starts a new session while retaining older saved records. Rotation, rate limits and unavailable storage can make the report incomplete; inspect any notice shown.

In the interactive serving terminal, Ctrl+E prints retained diagnostics for that runtime session, preserves the typed line and moves the cursor to its end. Ctrl+X, then Ctrl+K, opens a confirmation prompt: type exactly CLEAR and press Enter to delete saved diagnostics from all sessions in this project. Any other answer cancels. These shortcuts require interactive terminal input and output. Ctrl+C still stops the runtime and prints a newline.

The GUI’s Clear saved diagnostics uses the same typed CLEAR confirmation. Clearing deletes retained diagnostics, not task evidence or project documents; future failures are still recorded. Use doctor for a fresh health inspection separately—viewing or clearing diagnostics does not repair the reported cause.

Planning guidance cannot read all evidence

Refresh planning guidance with “Evidence is incomplete” means the read did not establish a readiness or completion decision. Inspect the specific failed limit: one file’s bytes, total evidence bytes, read count, result size, worker timeout or memory. This is not by itself evidence of a caching failure. Unchanged evidence files are reused within a request, and editor/guidance share the selected saved document.

Open Settings → Performance and limits, inspect the current values and preview a suitable preset or individual change. The default evidence-file ceiling is 1.5 MiB, while preview display length is 20,000 characters. Increasing one does not necessarily resolve the other. Saved limits apply to new requests; return to the item and refresh guidance. If a file is missing, ignored, malformed or inaccessible, fix that reported cause instead. The performance guide explains budgets and their costs.

For stale validation, inspect the named summary’s Validation evidence. Run supported checks through preview and confirmation; required retries may need Task recovery first. A completed task’s historical stale runs remain history: use a follow-up check for the current workspace. doctor does not run these checks or renew readiness authorization. See handoff and validation.

The command is not found

Confirm that the installer placed the command directory on PATH. Open a new shell so startup files are reloaded, then run day-shift --help. If the installer reported a destination outside your current PATH, add that directory according to its output.

Checksums or manifest metadata do not match

Stop using the artifact. Download the archive or installer, manifest, and checksum file from the same exact /downloads/<version>/ directory, then verify again. Do not treat a mutable latest pointer as immutable evidence.

The wrong license is selected

Run:

day-shift license status --format json

Inspect the resolved user-local license path. Use --license-file <path> for a one-off check without writing configuration.

Managed reminder regions remain

First confirm that the installed license verifies and suppresses reminders. Then preview and apply cleanup:

day-shift license cleanup-reminders --dry-run
day-shift license cleanup-reminders

The CLI appears to need the website

Normal installed CLI behavior is local-first and offline-capable. Website access is needed for public downloads, purchases, signed-file delivery or recovery, and documentation—not for ordinary repository workflows.

Migration planning is blocked

Run day-shift workspace migrate --check --format json, then inspect every work unit and finding. Ambiguous Basic, Structured, or Governed classification needs an explicit mapping. Root-order or parent-local task-sequence collisions need new explicit selections. Unsafe paths, duplicate identities, incomplete pairs, or unsupported artifacts must be repaired or dispositioned before apply; do not bypass them with manual moves.

If a previously reviewed plan is stale, generate a new --plan result and reauthorize its exact planDigest. A changed file, destination-presence condition, mapping, or order invalidates the old apply decision.

GUI planning is blocked or a preview is stale

Start with the selected artifact and current finding in GUI planning workflows. Save unsaved source edits before running planning actions. A missing task field needs a task refinement; an incomplete predecessor needs its owning workflow; an unresolved design decision needs an explicit answer. A scaffold or successful read-only review does not grant readiness authorization.

If a source, parent, registry or destination changed after preview, refresh the selected document and obtain a new preview. After a runtime restart, reconnect with the current runtime identity. Preserve a local draft when another tab saves a new version; compare or download it before choosing the saved version. For expired history cursors, request a fresh history page. Do not use an expired operation identity to redispatch a write.

If the action is unavailable, inspect whether the runtime has a concrete adapter and whether the current selection is eligible. Registration alone does not establish executability. A limited repository search needs a narrower query or directory, and an ignored file remains unavailable until the repository’s read policy permits it.

A repository write lock exists

Do not delete .day-shift/state/write.lock. An active owner or unknown liveness means wait. Expiry alone is not proof that takeover is safe; a stale lock needs disproven owner liveness and matching retained transaction evidence. If the lock belongs to another transaction, stop and inspect both identities.

A transaction is incomplete

Preserve .day-shift/state/transactions/<transaction-id>/ and the command’s JSON result. Identify each target as before, intended, retired, missing, or diverged, and keep the returned recovery fingerprint. Choose only an action the owning command reports as safe: roll-forward completes verified intended writes, while restore replays verified before-bytes.

A live lock, stale fingerprint, diverged target, missing staged content, unsafe restore, wrong transaction kind, or conflicting recovery receipt is a no-write recovery rejection. Reinspect instead of retrying or cleaning state manually. After verified recovery, retain the sanitized receipt and rerun the relevant no-write status, plan, or review.

For account, purchase, entitlement, recovery, or promised response questions, use the website’s support entry point; those policies are not defined by this troubleshooting guide.

Delivery guidance and external evidence

If Delivery reports a version conflict, keep your draft, inspect the latest record and deliberately reconcile it before saving. Keep my edits on the latest version changes the draft’s expected version; it does not save until you choose Save delivery record. A stale page cursor refreshes the first page while preserving the draft. After a runtime restart, reconnect to the current runtime and refresh evidence instead of replaying an import.

An unavailable or expired brief must be regenerated before export. Keep operator instructions separately if browser draft storage is unavailable or full. Expired historical evidence retains its digest and original provenance; unavailable content cannot prove a current successful delivery.

A pasted success log or URL remains reported or evidence-supplied. For optional authenticated evidence, inspect the local public trust key, exact project/source/work/environment binding, signature and expiry. Invalid or mismatched attestations remain unverified; do not change an outcome merely to obtain a verified label. Reject credentials and oversized files before retrying. See delivery guidance and evidence for limits and the attestation contract.

Project analysis is partial or loses its runtime connection

Check Project analysis for denied paths, stale citations, uninspected content and exhausted budgets. Filename discovery is not content coverage, and recorded phase status is not accepted completion. Explicit read-disclosure consent is needed for additional source evidence; ignore rules still apply. Revoke access when it is no longer needed. Narrow the remaining question and review the prepared continuation before sending it.

An already-open editor and chat retain drafts through disconnect/restart, with stale-data warnings and saving unavailable until verification succeeds. Preserve unsaved text before deliberate page reload. Use the current-project link after a runtime identity change and grant source scope again; cached presentation does not authorize new operations. See Project chat and planning updates for bounded source inspection and the distinction between deterministic qualification and optional live calibration.