Troubleshooting

The shell cannot find lumenlan after installation

macOS and Linux install to ~/.local/bin by default. Add that directory to your shell’s PATH, then open a new terminal. You can also choose an existing command directory with --install-dir. Windows adds its default directory to the user PATH, but the current PowerShell may still have the old environment. Open a new window before running lumenlan version.

The installer reports SHA-256 or version probe failure

The installer rejects a file that differs from the stable SHA256SUMS, then runs the downloaded binary to check its version. Confirm the system clock, HTTPS connection, disk space, and retry once. A corporate proxy that replaces downloaded content will trigger this protection. Do not bypass the check; use the manual download page to obtain the binary and checksum list, then verify them independently on the machine.

Exit code 2 or a blocked outcome

Exit code 2 means the action did not have all prerequisites; it is not a failed check. Read the JSON outcome, diagnostics, and capability information. Confirm dependency tools, platform sandbox, grant expiration, machine, and project. Windows workspace is intentionally blocked without a qualified sandbox backend. Move that work to a supported target instead of changing it to unsandboxed execution.

Exit code 3 or an invalid outcome

Exit code 3 means a specification, field, profile, or boundary is invalid. Confirm the request uses a registered version, verification contains no free-form command or dynamic script, and a workspace process, script, or adapter matches its granted scope. Correct the input before running it again; invalid is not an ordinary business failure to retry unchanged.

stdout is not valid JSON

The CLI itself writes only contract JSON to stdout. Check whether a wrapper, terminal plugin, or MCP setup is printing a banner there. Help, diagnostics, and logs belong on stderr. Run lumenlan --help separately when you need human-readable syntax.

An MCP client cannot connect

Confirm the same user environment can find lumenlan mcp serve --transport stdio, and do not add a network address to the configuration. Restart the client after changes. If it still fails, save stderr without sensitive content together with the CLI version, operating system, and exit code, then contact support@lumenlan.com.