Wayland Core Troubleshooting

This page covers the wayland-core CLI engine. For the desktop app, see Desktop App Troubleshooting. Each entry is a problem, its cause, and the fix.

Start with the doctor

Before anything else, run the built-in diagnostics:

wayland-core --doctor

It checks your configuration and environment and reports what it finds. Many of the problems below show up there first.

No API key found

Problem:

No API key found. Provide via --api-key, config file, or environment variable

Cause: no credential resolved for the active provider.

Fix: supply a key by any of the three routes. A flag wins over the environment, which wins over the config file:

wayland-core --api-key sk-... "hello"
# or
export ANTHROPIC_API_KEY=sk-...

For Anthropic you can also sign in with your Claude account: wayland-core --login. See Provider and Auth Errors.

Invalid key or model

Problem: an API error like 401 (invalid key) or 404 (model not available).

Cause: a wrong or inactive key, or a model your key cannot access.

Fix: verify the key is correct and active. Check that --model is spelled correctly and that your account has access to it. A 413 request-too-large error means the conversation history is too long: restart, or lower --max-turns.

Command timed out

Problem:

Command timed out after 120000ms

Cause: a Bash tool command ran past its timeout. The default is 120 seconds.

Fix: raise the timeout through the tool’s timeout parameter for the slow command. If a command routinely runs long, consider whether it should run unattended at all.

Grep is slow or ripgrep is missing

Problem: searches are slow, or you expected ripgrep behavior.

Cause: the Grep tool prefers ripgrep and falls back to the system grep when ripgrep is not installed. The fallback works but is slower.

Fix: install ripgrep for faster search:

brew install ripgrep        # macOS
sudo apt install ripgrep    # Debian or Ubuntu

Crashes and where logs live

Problem: the engine exits unexpectedly, or the TUI dies.

Cause: a genuine crash, or a previous run that did not exit cleanly. The engine keeps a crash sentinel so it can detect a prior dirty exit on the next start.

Fix:

Read the log file. The TUI writes to $WAYLAND_HOME/logs/wayland-core.log (by default ~/.wayland/logs/).
Raise verbosity for the next run with RUST_LOG, for example RUST_LOG=debug wayland-core "...", then reproduce and read the log.
If the engine reports a dirty prior exit on start, that is the sentinel noticing the last run did not shut down cleanly. It is informational; the new run proceeds.

Windows note

On Windows, deeply recursive work historically risked a stack overflow. The engine runs that work on a dedicated thread with its own stack, so this is handled. If you still hit a stack-related crash on Windows, capture the log file and report it. See Contributing for where issues go.