Troubleshooting

Diagnose the current Compose, Run locally, Connect, and Status lifecycle.

Keep each lifecycle boundary separate. A valid composition does not imply a running process, and a running process does not imply a connected Console object.

First checks

test -f ./support-desk/lenso.app.json
cd ./support-desk
lenso system dev --system-file ./lenso.app.json --dry-run --json
curl -sS http://127.0.0.1:3030/api/console/v1/system

The Console request also requires an authenticated actor with console.system.read.

Common symptoms

Symptom	Check	Action
`lenso.app.json` is missing	Compose output directory and source pack path	Run the compose command again from the directory that owns the pack.
Connected local startup fails	The first failed stage from `lenso dev up --console-root ...`	Fix that Host, Provider, Store, Console, artifact, or connection stage before retrying.
A business Service cannot enroll	Signed receipt in `.lenso/console-connect.json`, allowlisted keys, and loopback `baseUrl`	Correct the Service identity or contract; do not bypass signed enrollment.
Connect rejects a business Service	Active signed enrollment and advertised Core contract	Reapply the exact bundle with `lenso console connect`; do not hand-edit its receipt.
Connect rejects the topology	Topology SHA-256 digest and Management Binding in the bundle	Regenerate the bundle from the composed app; do not submit a different topology under the old digest.
Local Control Adapter appears unenrolled	Adapter ID and binding	Use `lenso-local-control-adapter` with `workload-control:<system>`; this CLI-owned Adapter does not use business enrollment.
A Module Surface is absent	Module Release, UI artifact, contract, and Surface Grant digests	Reconnect the exact app whose receipt binds all of those identities.
Adapter connection is `unavailable`	Local Control Adapter process and target-owned status endpoint	Restart the local run. Workload observation remains `unknown`; mutation is not queued.
An object is `incompatible`	Protocol, schema, capability, and artifact details in its reason	Align the declared contract and reconnect the same identity.
An object is `unmanaged`	Whether the observed or enrolled object belongs to the current topology and Management Binding	Add it to an intentional future composition or leave it outside this connected System.
Product acceptance cannot find a repository	Sibling checkout names or root override variables	Provide `LENSO_FRAMEWORK_ROOT`, `LENSO_CLI_ROOT`, and `LENSO_CONSOLE_ROOT`.
Product acceptance cannot start PostgreSQL	`initdb`, `postgres`, and `pg_isready` on `PATH`	Install local PostgreSQL binaries or provide a disposable `LENSO_ACCEPTANCE_DATABASE_URL` whose database name contains `acceptance`.
Browser acceptance cannot start	Headless Chrome-compatible browser and installed dependencies	Run `pnpm install --frozen-lockfile`, then retry the explicit acceptance command.

Compose

The bare Support Desk blueprint contains auth, notification-worker, and support-api:

lenso app compose ./support-desk --blueprint support-desk --apply

The Support Ticket and Story Modules come from the acceptance capability pack, not from the bare blueprint. Run the full product command from the lenso-examples repository root; see Product Blueprints.

If the source pack path is relative, changing the current directory changes what the CLI can resolve. --apply writes the generated composition atomically. Inspect support-desk/lenso.app.json rather than editing it by hand.

Run locally

Start the connected local path from the composed Host directory:

cd ./support-desk
lenso dev up --console-root ../lenso-console

The command remains in the foreground and reports the exact Host, Provider, Store, Console, artifact, or connection stage that fails. Ctrl-C stops only processes started by that invocation.

Use the System Sandbox dry run only when you need to isolate composition and Adapter validation from the connected Host, Provider, and Console path:

lenso system dev --system-file ./lenso.app.json --dry-run --json

If a previous sandbox run still owns the Adapter socket or processes, use its bounded cleanup entrypoint:

lenso system dev --system-file ./lenso.app.json --cleanup

Cleanup targets only resources recorded for that local run.

Connect

lenso dev up --console-root writes and applies the exact local bundle before reporting the System ready. To retry a separately prepared bundle, use:

LENSO_CONSOLE_TOKEN='<operator-session-token>' \
  lenso console connect \
  --console-url http://127.0.0.1:3030 \
  --bundle .lenso/console-connect.json

Use --token-file with a private regular file for non-interactive operation. Do not edit the bundle: regenerate it from the composed app when an identity, release, artifact, topology, or binding changes.

The CLI submits each signed receipt to the underlying enrollment boundary and then applies the digest-bound System Connection:

POST /api/console/v1/enrollment-receipts
POST /api/console/v1/system/connect

Console validates both signatures using its server-only allowlist. Local baseUrl values must be loopback HTTP. The System request must carry the exact lenso.system.v2 topology, its SHA-256 digest, and the Management Binding for the same System. There is no unsigned registry write that substitutes for this path.

Status

GET /api/console/v1/system

Connection state and Workload operational state are different dimensions:

Dimension	Objects	Values
Connection projection	System, Service, Module, Surface, Adapter	`connected`, `unavailable`, `incompatible`, `unmanaged`
Workload operation	Workload observation	target-owned states such as `running`, `suspended`, `stopped`, `unknown`

unmanaged describes an observed or enrolled object outside the current topology and Management Binding. A business Service declared by the topology cannot connect without active enrollment.

When the Local Control Adapter is unavailable, Workload operational state is unknown. Console rejects control requests immediately; it does not queue, reroute, or infer a result from process state.

Surface opens but business data fails

The browser must call the generated client through Surface Gateway. Confirm that the connected receipt binds the exact Module identity, Module Release digest, console_ui_esm artifact digest, Business API contract digest, and allowed operation IDs.

Service credentials remain in Console Service. Do not add credentials to the browser or call the business Service directly from the Surface.

Product acceptance

Run the complete black-box entrypoint explicitly:

pnpm acceptance:support-desk

The runner resolves lenso, lenso-cli, and lenso-console as sibling checkouts by default, starts disposable PostgreSQL when no acceptance database URL is supplied, and cleans its temporary directory. See Examples for all prerequisites and overrides.