Troubleshooting

Diagnose common host, module install, Console, service, capability pack, and release-check problems.

Start by separating host state from module state:

git status --short
lenso module doctor
curl -sS http://127.0.0.1:3000/api/admin/modules | jq .

If the host is running but the Console does not show the expected module, restart both API and worker after install changes.

Common symptoms

Symptom	Check	Fix
Console URL is unavailable	`lenso console doctor` and Console workload health	Restore the Console Service or apply a reviewed upgrade.
Console reports `Operator required`	`GET /bootstrap/v1/status`	Run `lenso console operator bootstrap`, then restart Console API and Worker.
Console opens but a managed Module is missing	System Registry and enrollment evidence	Verify the Module Release, Console UI artifact, and managed-Service enrollment.
Service provider is installed but unhealthy	`lenso service doctor <provider> --json`	Start the Service, fix its declared readiness endpoint, or follow the reported recovery action.
App lifecycle next step is unclear	`lenso app next`	Run `lenso app explain` to see generated-state, module, and service actions separately.
Launchpad App Change Plan is empty	`.lenso/app-change-plan.json`	Run `lenso app plan --write-plan` or `lenso app plan --addon <name> --write-plan`.
Capability pack is not shown in Launchpad	`lenso capability check <pack-dir>`	Fix the pack manifest, then rerun `lenso app compose --repo-root . --pack <pack-dir> --write-plan` or `--apply`.
Launchpad App Change Plan is blocked	Console Launchpad plan panel	Review blocked changes; unsupported addons usually mean choosing a supported blueprint or addon.
Launchpad App Proof is empty	`.lenso/app-proof.json`	Run `lenso app verify --write-proof` in the generated app root.
Launchpad App Proof is drifted	`lenso app diff`	Preview safe generated-state repairs with `lenso app repair --dry-run`, then run `lenso app repair` if the plan is right.
A Service installation changed but nothing happens	`lenso service doctor <provider> --json`	Reconcile the Host and follow the reported restart or recovery action.
Auth works locally but sessions are slow	`auth.session_cache` and `REDIS_URL`	Install `auth --profile redis-session-cache` and provide Redis separately.
Redis auth profile fails at runtime	Redis service availability	Start Redis and confirm `REDIS_URL` points at the right database.
CORS blocks browser requests	`CORS_ALLOWED_ORIGINS`	Add the frontend origin or use the generated local defaults.
OTLP exporter errors in local smoke	`OTEL_EXPORTER_OTLP_ENDPOINT`	Unset it for normal local smoke or start observability services.
`just generated-check` fails	git diff	Do not hand-edit generated files. Run `just generate` and commit the generated artifact changes with the source change.
`just release-check` fails on infrastructure	Docker, ports, Postgres	Fix local services first, then rerun the gate. Treat code failures as release blockers.

Console is unavailable or stale

Inspect the independent installation first:

lenso console doctor --help

Plan an immutable Release upgrade when the installed version is stale:

lenso console upgrade --help

Then open the configured Console Service URL. The local source checkout defaults to:

http://127.0.0.1:3030/

Module install did not appear

Check the local receipt:

cat .lenso/module-installs.json | jq .

Check the environment written by install:

grep -E 'LENSO_MODULE_' .env

Then restart API and worker. Linked module installs can update Cargo.toml and src/lib.rs, so rebuild the host when necessary.

Service is not ready

Run:

lenso service workspace check
lenso module doctor

Doctor checks declared services in .lenso/module-services.json and reports:

service not configured;
service disabled;
service ready;
manual service not ready;
stale host-started state;
ready URL not responding.

If the provider is an external service, start it yourself and make sure the readyUrl responds before starting the host.

Launchpad App Change Plan

App Change Plan gives operators and agents a reviewable file before generated state changes are applied:

lenso app plan --write-plan
lenso app apply .lenso/app-change-plan.json --dry-run

For addon changes, include the addon name:

lenso app plan --addon support-sla --write-plan

For multiple addon requests, use App Composer:

lenso app compose --repo-root . --addon support-sla --addon customer-profile --write-plan
lenso app next
lenso app explain

For capability pack requests, pass the pack directory:

lenso capability check ./capabilities/support-sla
lenso app compose --repo-root . --pack ./capabilities/support-sla --write-plan
lenso agent task --for-capability support-sla "continue the requested work"

If the plan is blocked, do not apply it. Use the blocked item message and command to pick a supported addon or pack, fix the generated state first, or continue manually.

Launchpad App Proof drift

App Proof checks generated control-plane state for product blueprints:

lenso app verify --write-proof
lenso app diff
lenso app repair --dry-run

Use the dry run output to decide whether repair is appropriate. Repair can restore generated Launchpad, workspace, and system entries or missing scaffold directories. It does not overwrite existing service source files, and it should not delete unknown services.

Service manifest URL does not respond

Open the manifest directly:

curl -sS http://127.0.0.1:4100/lenso/service/v1/manifest | jq .

Then ask the CLI for the provider’s exact diagnostic evidence:

lenso service doctor billing --json

Fix the declared manifest, readiness URL, credentials, or deployment target rather than bypassing the Service installation record.

Generated artifacts changed

When just generated-check fails, inspect the diff:

git diff -- contracts generated

If the diff matches your Rust/OpenAPI change, keep it. If it does not, fix the source and regenerate:

just generate
just generated-check

Ports are busy

Change the host port for one shell:

HTTP_PORT=3010 lenso serve

For first-user smoke defaults, use:

FIRST_USER_SMOKE_HTTP_PORT=3011 \
FIRST_USER_SMOKE_PROVIDER_ADDR=127.0.0.1:4111 \
just first-user-smoke

Release gate fails

Run the smaller checks to find the failing layer:

just fmt-check
just rust-check
just test
just generated-check
just arch-check

If only Docker or Postgres is failing, fix local infrastructure and rerun. If formatting, compile, tests, generated contracts, or architecture checks fail, treat the failure as release-blocking code work.