Troubleshooting
The most common ways things go sideways, and how to undo each one.
Run lly doctor first. It checks the binary, the plugin directory, the runtime, and reachability of rc.lilylabs.io. Most of the failures below show up there as a single red line before they ever bite a real workflow. See lly doctor for the full output reference.
Install and PATH
lly: command not found
The install script writes the binary to /usr/local/bin/lly. If your shell does not have that directory on PATH, the command will not resolve. Re-run the installer, then open a fresh shell.
lly doctor: rc.lilylabs.io unreachable
Corporate networks usually terminate egress at a proxy. The CLI honours the standard HTTPS_PROXY and HTTP_PROXY environment variables for every outbound request, including the install script and plugin downloads.
Authentication
lly login cannot open a browser
On headless boxes, SSH sessions, and CI runners there is no browser to launch. Use --print-url to print the auth URL and open it manually from another machine. The WebSocket callback works across networks as long as your CLI host can reach auth.lilylabs.io.
lly void deploy: 401 unauthorized
Access tokens are short-lived. After about a week of inactivity the cached credential in ~/.lly/credentials expires and every authenticated call returns 401. Re-run lly login. The CLI never refreshes tokens silently, by design.
Plugins
lly plugin install: signature mismatch
Each plugin manifest is signed at publish time. A mismatch almost always means the local manifest cache is stale and points at an old binary. Clear the cache and retry. If it persists past a fresh install, treat it as a real signature failure and report it.
Builds
lly nextjs void: out of memory
The Next.js plugin spawns an esbuild worker for client bundles and a Node helper for any 'use server' rewrite. Both inherit Node's default 1.7 GB heap. Large monorepos can blow past it during the import-graph walk. Bump the heap before running the build.
Runtime and deploys
Live URL returns 503
The CAP fleet cold-starts a brick the first time a placement gets traffic. The initial WASM compile and module instantiation takes up to 30 seconds for large bricks. A 503 inside that window is expected. Wait, then tail logs to confirm the boot completed.
Still stuck
Send the output of lly doctor, the exact command you ran, and the full error to support@lilylabs.io. Most tickets are answered the same day. For installation and connectivity questions, the lly doctor page documents every check the CLI performs at startup.