Troubleshooting

Common issues and how to resolve them. If none of these fit, /support in the terminal UI emails Pathvela support with diagnostics prefilled.

"Invalid API key or token" (401)

The agent couldn't authenticate.

  • Check what's stored: lily key status. It reports whether a key is present and your account.
  • Re-set it: lily key set sk-lily-.... Keys come from platform.pathvela.com. New keys look like sk-lily-…; older sk-agent-… keys still work.
  • In the SDK, make sure apiKey is actually set — createLilyAgent throws without it. In CI, pass it via the POOLOT_API_KEY environment variable, which takes precedence over any stored key.

"Payment required" or the run stops on credits (402)

You're out of credits.

  • Check your balance: /subscription in the terminal UI, or await agent.getMe() in the SDK (it returns your balance).
  • Top up in the developer console at platform.pathvela.com.

The CLI can't reach the backend

The agent talks to agent.pathvela.com. Behind a corporate firewall or proxy, that request can be blocked.

  • Confirm you can reach it: curl -I https://agent.pathvela.com.
  • If you're behind an HTTP proxy, set the standard HTTPS_PROXY / HTTP_PROXY environment variables so the CLI's requests go through it.
  • Check that TLS interception (a corporate root CA) isn't breaking the connection.

lily isn't found after installing

The installer puts lily on your PATH, but your current shell may not have picked it up yet.

  • Open a new terminal, or re-source your shell profile.
  • Confirm the install with lily --version.

Auto mode won't start or the browser can't connect

See Auto mode for the full flow. Common causes:

  • Ports busy. The bridge uses the first free port in 8791–8793 and refuses to start if all three are taken. Free one up, or pass --port.
  • Wrong pairing code. The code is regenerated each start. Check the current one with lily bridge status, or run lily bridge reset to revoke pairing and start fresh.
  • Nothing happening. Check lily bridge log for what the background service is doing.
  • Only pathvela.com can connect to the bridge — make sure you're pairing from there, not another origin.

Updates aren't applying

The CLI auto-updates by default.

  • Force the latest now by re-running the installer (curl -fsSL https://agent.pathvela.com/install.sh | sh).
  • If you set LILY_NO_AUTO_UPDATE or pass --no-update, updates are intentionally skipped — unset it to resume.
  • For the background server, lily server reload moves live sessions onto the newest binary.

The agent won't edit files

If you're using a headless lily run, that's by design — it works in a read-only profile so it's safe in scripts. Use the interactive terminal UI (lily) or the browser via auto mode when you want the agent to make changes.

SDK: the browser agent won't start

The WebAssembly engine needs a secure context and a couple of allowances — see Browser vs Node and SDK installation.

  • Serve your app over HTTPS or localhost — WebAssembly needs a secure context.
  • Your Content-Security-Policy must allow wasm-unsafe-eval (script) and a connection to the backend.
  • Serve the engine's assets yourself in production and point to them with assetBase.

SDK: a run ended without an answer

Check result.status — a run can end for reasons other than success (it hit a budget, was aborted, or the agent got stuck). Going to production shows how to handle each case.

Still stuck?

Run /support in the terminal UI to email Pathvela support with diagnostics attached, or reach out from platform.pathvela.com.