JSON Output and Error Contract

JSON Output and Error Contract

Language: English · 简体中文

Native passthrough exception and input discovery

In v0.18.5 native lwc cg queries forward stdout, stderr and exit status unchanged; the native MCP result is preserved. The JSON envelope below applies to LWC-owned commands, not native payloads. Use lwc contract remember, lwc contract plan-create, lwc contract plan-revise, lwc contract discussion, lwc cg tools and lwc cg help COMMAND for exact schemas. Compact receipts have explicit expanded reads.

LWC uses JSON as its automation contract. Successful commands return structured JSON on standard output; failures return a stable error envelope on standard error. Use the code to choose a recovery branch, the message to explain the current instance, and details to determine retryability and whether canonical state already changed.

Error envelope

{
  "error": {
    "code": "store_not_found",
    "message": "no project Wiki was found from the current directory",
    "details": {}
  }
}

The process exits non-zero and writes the envelope to standard error. details varies by code and can contain identifiers, paths, limits, retry guidance, Work metadata, safety checkpoints, or recovery commands.

Do not build automation around message text. New releases may improve wording or add details without changing the code's meaning.

Canonical partial success

Some recovery and publication failures happen after SQLite canonical state has changed. Those errors explicitly report facts such as canonical_committed, checkpoint_restored, or rolled_back, plus a recovery command.

When one of these flags is true:

1. do not repeat the original logical edits;
2. preserve the error JSON and returned identifiers;
3. run the exact recovery command in the same project and scope;
4. wait for returned Work;
5. finish with lint and graph verify when the graph is enabled.

Treat a missing partial-success marker as “not proven,” not as proof that nothing changed. Inspect canonical state before a manual retry.

Scope and Store

Code	Meaning	Correct response
store_not_found	No Wiki exists at the selected scope	Run from the intended project, or initialize that exact scope
scope_not_supported	The command does not support the selected scope	Use project or global; reserve all for supported reads
project_root_invalid	The explicit project root is unusable	Correct or remove LWC_PROJECT_ROOT
project_root_mismatch	Current directory is outside the explicit root	Change directory or select the intended root
project_root_escape	A resolved path escapes the authorized project	Keep the path inside the project or use a documented acknowledgement
project_scope_conflict	Discovery found conflicting project Wikis	Run from the precise project boundary
invalid_store_path	A Store-owned path is unsafe, missing, or has the wrong type	Inspect symlinks and ownership; do not replace state blindly
unsupported_store_version	The database is newer or unsupported	Upgrade LWC; do not force a downgrade write
corrupt_store	Required schema or invariants are invalid	Stop writes and follow checkpoint recovery
database_busy	A bounded writer or restore lock is active	Respect retry details and retry the exact command

Input, Source, Page, and ingest

Code	Meaning	Correct response
invalid_input	A field violates the command contract	Correct the named field
invalid_limit, invalid_offset	Pagination is outside the accepted range	Use the bounds reported by the command
input_too_large	A CLI input exceeds the bounded reader	Split or reduce the input
invalid_utf8	Text input is not valid UTF-8	Convert encoding before ingest
possible_secret_detected	Input resembles a credential or secret	Remove the secret; do not bypass the scanner for real credentials
external_source_requires_acknowledgement	The Source is outside the project	Confirm authorization, then use the explicit acknowledgement flag
source_not_found	The requested immutable Source ID does not exist	Refresh IDs with source list
source_in_use	Pages still cite the Source	Inspect source refs; update Pages before removal
source_status_unstable	A tracked file changed while being inspected	Retry after the writer finishes
source_diff_too_large	Diff input exceeds the safe comparison budget	Compare a smaller revision or use an external bounded review
page_not_found	The Page slug does not exist	Check scope, changeset selector, and slug
page_in_use	Another Page links to the target	Repair inbound links before removal
invalid_provenance	Provenance is outside the supported vocabulary	Use a documented provenance value
ingest_job_not_found	No ingest job exists for that Source	Inspect ingest list and Source state
invalid_ingest_state	The requested transition is illegal	Continue from the reported current state
ingest_integration_required	Completion gates are not satisfied	Add a cited source summary and integrate or justify no derived Page

Changesets and checkpoints

Code	Meaning	Correct response
changeset_exists	A draft with that name already exists	Continue, discard, or choose another validated name
changeset_not_found	The named draft is absent	Inspect changeset list
changeset_empty	The draft has no publishable change	Discard it or stage the intended update
changeset_lint_failed	Draft lint blocks publication	Fix the reported issues in the draft
changeset_conflict	Live state advanced across a touched identity	Review live and draft; rebuild the draft from the current baseline
changeset_rollback_conflict	A later live write makes inverse application unsafe	Preserve later work; use a deliberate new change instead
changeset_corrupt	Draft, binding, or inverse data failed integrity checks	Stop and preserve evidence for recovery
changeset_committed_cleanup_failed	Canonical commit succeeded but draft cleanup failed	Run the returned recovery command; do not republish content
changeset_committed_materialization_failed	Canonical commit succeeded but Markdown projection failed	Follow recovery details, then lint
changeset_rolled_back_graph_projection_failed	Rollback succeeded but graph repair failed	Re-run the reported rollback recovery and verify the graph
checkpoint_not_found	The named checkpoint does not exist	Inspect checkpoint list
checkpoint_invalid	The checkpoint failed identity, schema, or integrity validation	Do not restore it; choose a verified checkpoint
checkpoint_restored_materialization_failed	Database restore succeeded but files were not rebuilt	Use the exact recovery command and revalidate
checkpoint_restored_projection_failed	Database restore succeeded but graph projection failed	Recover the project-scope projection and run graph verify

Work and projections

Code	Meaning	Correct response
work_not_found	That Work ID is absent from the selected runtime	Check scope and changeset selector
work_busy	Another Work owns the mutation lane	Watch the active Work or retry later
work_cancelled	Cooperative cancellation reached a terminal state	Resume only if the Work is resumable and still desired
work_not_resumable	The Work state cannot be resumed	Inspect the result and start the appropriate new operation
work_invalid	Durable Work metadata failed validation	Preserve the runtime and investigate; do not edit files manually
artifact_busy	A managed artifact cannot be replaced safely	Close the reader or wait for the owning process
artifact_write_failed	Canonical state is valid but a generated artifact failed	Run materialization recovery and validate ownership
graph_disabled	No document-graph engine is selected	Enable an intended engine only with user authorization
graph_node_not_found	The queried graph node is absent	Verify the graph and confirm identifier syntax
graph_projection_failed	Canonical mutation succeeded but projection could not queue or run	Follow details, watch Work, then verify
grafeo_error, surrealdb_error	The selected embedded engine rejected an operation	Inspect engine state; reproject only after canonical health is proven

CodeGraph, conversion, and integrations

Code	Meaning	Correct response
codegraph_runtime_missing	The pinned runtime is not installed	Run cg init only after authorization
codegraph_index_missing	The project has no usable code index	Run project-scoped cg init and inspect status
codegraph_download_failed	The runtime asset could not be fetched	Check network and retry; do not substitute an unverified binary
codegraph_checksum_mismatch	Downloaded bytes failed checksum verification	Stop; discard the asset and investigate the source
codegraph_command_failed	CodeGraph returned a command failure	Inspect its structured stderr and project status
trans_disabled	No conversion adapter is selected	Configure MarkItDown or AnyDoc intentionally
trans_executable_missing	Selected adapter is not available on PATH	Install the chosen upstream tool or change configuration
trans_unsafe_args	Stored adapter arguments violate the safety policy	Remove unsafe positional, output, shell, or credential flags
trans_timeout	Conversion exceeded its configured deadline	Inspect the input and raise the bounded timeout only when justified
trans_publish_race	Another writer created the output first	Choose a new output; LWC will not overwrite it
unknown_agent_target	The requested Agent adapter is not registered	Use lwc agent status --target all --location global and an exact target name
agent_config_conflict	A host-owned configuration changed incompatibly	Review the conflict; do not overwrite user configuration blindly
hook_input_too_large	The Agent event envelope exceeds the Hook budget	Reduce host payload or use the supported envelope
invalid_project_path	MCP received a relative, root, or invalid workspace	Send an absolute project directory
view_bind_failed	Viewer could not bind the loopback port	Use --port 0 or free the selected port

Escalation checklist

Before reporting a bug, collect:

lwc --version
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

Include the exact command, error JSON, operating system, whether the command was live or draft-scoped, and a minimal reproduction with secrets removed. See Troubleshooting-and-FAQ and Recovery and maintenance.