--- title: Troubleshooting description: 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 ```sh 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:`; 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`: ```sh 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](/docs/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: ```sh 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: ```sh 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: ```sh 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: ```sh LENSO_CONSOLE_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: ```text 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 ```text 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: ```sh 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](/docs/examples) for all prerequisites and overrides.