Troubleshooting and FAQ

Troubleshooting and FAQ

Language: English · 简体中文

Troubleshoot LWC from the outside inward: confirm binary and scope, inspect canonical health, inspect durable Work, then inspect optional indexes. Do not start by deleting .lwc state.

Minimum diagnostic bundle

Run only against the affected scope and redact paths or content before sharing:

lwc --version
lwc --scope project context --limit 1
lwc --scope project config show
lwc --scope project lint --limit 100
lwc --scope project work list
lwc --scope project graph status
lwc --scope project graph verify
lwc --scope project cg status
lwc agent status --target auto --location global

Record the exact command, exit status, error JSON, current directory, operating system, LWC version, and whether the failure happened before or after a canonical mutation.

Do not paste Source content, Page bodies, stored conversion arguments, host configuration, or private paths unless required and authorized.

Read the error contract first

A failed command returns structured JSON on standard error:

{
  "error": {
    "code": "database_busy",
    "message": "another short Wiki write is active; retry this exact operation",
    "details": {
      "retryable": true,
      "retry_after_ms": 100,
      "work_command": "lwc work list"
    }
  }
}

Branch on code, not English message text. Inspect details for retryability, canonical partial success, Work IDs, safety checkpoints, and exact recovery commands.

Wrong Wiki or missing Store

Symptoms include store_not_found, unexpected Pages, or a database path outside the intended repository.

pwd
lwc --scope project context --limit 1
lwc --scope global context --limit 1

Run from the project directory or a child. Remove routine shell exports of LWC_PROJECT_ROOT. Use that variable only for one intentionally selected root, with the current directory inside it.

If project_scope_conflict appears, more than one Wiki exists inside the explicit boundary. Choose the actual project directory instead of widening the root.

Busy database or Work

database_busy means a short SQLite writer or restore boundary is active. Respect retry_after_ms and retry the exact operation after inspecting Work.

work_busy means one state-changing Work owns the selected runtime:

lwc --scope project work list
lwc --scope project work status <work-id>
lwc --scope project work watch <work-id>

Do not remove the active marker. Cancel only when the operation should genuinely stop, then watch until cancelled.

Lint failures

lwc --scope project lint --limit 100

Common issue classes:

• missing summaries or provenance;
• uncited Pages;
• orphan Pages or dangling Wiki links;
• completed ingest with no shared derived Page or audited reason;
• missing, duplicate, or orphan FTS rows.

Fix canonical content for knowledge issues. Use maintenance reindex only for index-integrity issues; use maintenance materialize only for generated Markdown.

In a sparse changeset, lint must evaluate live baseline plus draft delta. Do not copy unchanged live Pages into the draft or use --allow-lint-issues to hide an overlay bug.

Search misses the expected Page

lwc --scope project search "exact wording" --limit 10 --explain
lwc --scope project search "natural paraphrase" --limit 10 --explain

Check:

1. the Page exists in the selected scope;
2. title and summary use the terms users actually ask;
3. the query has searchable terms after normalization;
4. target, kind, and granularity filters are correct;
5. a source-summary Page did not intentionally suppress its paired raw Source in auto mode;
6. manual weight or feedback did not demote the result;
7. lint reports no search-index inconsistency.

Do not add a global positive weight before fixing stale or vague content.

Document graph unavailable or inconsistent

lwc --scope project config show
lwc --scope project graph status
lwc --scope project work list
lwc --scope project graph verify

• graph_disabled: enable an engine only with explicit project consent.
• Work still active: watch it.
• missing, mismatched, or stale verification entries: queue a full projection by setting the intended engine explicitly, watch Work, then verify again.
• Draft graph issue: repeat all Work and graph commands with the same --changeset selector.

Never edit Grafeo or SurrealDB files directly.

CodeGraph unavailable

cg status separates runtime installation from project initialization:

lwc --scope project cg status

• runtime missing: cg init downloads the pinned release only after explicit consent;
• runtime installed, project uninitialized: run cg init in that project;
• index stale: use the supported forwarded cg sync command;
• external path rejected: run from the intended project and use project-contained paths.

CodeGraph is not a separate MCP entry. If an Agent still shows codegraph, refresh the LWC AgentTarget integration and inspect owned legacy-entry migration.

Conversion failures

lwc --scope project config show
lwc --scope project trans input.docx --output converted/input.md

• trans_disabled: select an engine first.
• trans_executable_missing: install the selected optional engine outside LWC, then retry.
• timeout: inspect file size and adapter behavior before increasing the bounded timeout.
• trans_unsafe_args: remove path, output, or credential overrides from stored arguments.
• output exists: choose a new path; create-new safety prevents overwrite.

Conversion success is not Source ingest. Review the Markdown before source add.

Agent integration drift

lwc agent status --target codex,claude,pi --location global

modified means one tracked path differs from the installation receipt. Inspect it before refresh; the difference may be a valid user edit.

Use --print-config for read-only review. Refresh should be byte-idempotent without drift, and uninstall must preserve foreign content. Never fix an adapter by copying files from a maintainer-specific tool or HOME.

Viewer issues

• use --port 0 when a fixed port is busy;
• use --no-open when the platform browser launcher fails;
• Code Graph remains unavailable until explicitly initialized outside Viewer;
• Word Graph requires one to eight searchable terms and remains paginated;
• stale data must be repaired through CLI, then inspected in a new Viewer process.

Viewer requests must not mutate durable state. A write method should return HTTP 405.

Canonical partial success

Errors such as graph_projection_failed, checkpoint_restored_materialization_failed, or committed changeset cleanup failures may mean canonical state already changed.

Inspect fields including:

• canonical_committed;
• checkpoint_restored;
• safety_checkpoint;
• graph_work;
• recovery_command or recovery_commands.

Execute the exact recovery command, then rerun live acceptance. Do not repeat business mutations or discard the draft until the contract says cleanup is safe.

When to report a bug

Report a reproducible issue when:

• typed state contradicts canonical readback;
• a documented idempotent retry creates duplicates;
• live and draft selectors leak Work or graph state;
• Viewer or MCP performs an undocumented durable write;
• graph verify stays inconsistent after a successful documented rebuild;
• install, refresh, or uninstall overwrites foreign host content;
• a supported platform package fails checksum or version verification.

Include the smallest non-sensitive reproduction and whether cleanup is safe. Preserve a failed draft or checkpoint until maintainers confirm it is no longer needed.

Frequently asked questions

Should every command export LWC_PROJECT_ROOT?

No. Run lwc from the project or one of its descendants. Set the variable only when you intentionally need to cap discovery at a selected root.

Is CodeGraph downloaded for every project?

No. The pinned runtime is installed once per user and reused until upgraded. Each project keeps its own index because source trees and revision state are project-specific.

Should CodeGraph be registered as a second MCP server?

No. LWC exposes CodeGraph behind lwc_explore in code or all mode. Agent hosts register only the lwc MCP server.

Does a returned Work mean the operation is finished?

No. It means durable execution was queued. Use work watch and require a successful terminal state before acceptance.

Can generated Markdown be repaired by editing it?

No. SQLite is canonical. Use maintenance materialize, then validate the projection.

Does automatic Agent detection authorize installation?

No. Detection only preselects likely installed hosts. Interactive confirmation or explicit --yes determines installation.

Next: Recovery and maintenance