Troubleshooting

Provider prompt sending fails

If sending a prompt produces an error instead of streaming a reply, check in this order:

1. Is the provider installed? Run which codex, which opencode, which agent, etc., from the shell Verde was launched in. GUI launches on some platforms inherit a different PATH than a terminal — relaunch Verde from a terminal if you suspect this.

   bash

   which codex
   which opencode
   which agent

2. Is the provider authenticated? Re-run the provider's login command and confirm credentials are still valid:

   bash

   codex login
   agent login

   Claude Code is authenticated through its own SDK; Verde has no Verde-side login for it. Make sure the Claude Code binary and node are both reachable from the shell environment Verde was launched from.

3. Is the project imported? Verde runs the provider against the imported project directory. A provider CLI in a different working directory will not see the same files.

4. Check the logs. Provider helper stderr is written to the runtime log alongside Zig panics. On Linux:

   bash

   tail -f ~/.local/share/verde/Native/logs/verde.stderr.log

For provider-specific setup, see Provider setup.

Provider readiness does not update

After installing a provider CLI or completing its login flow, return to Connect an AI provider and choose Check again. If its state still says CLI not found, launch Verde from the same shell where the provider command works; desktop launchers can inherit a different PATH. If it says Sign-in needed, run the provider's login command outside Verde and retry. A timed-out or failed probe appears as Could not verify and should be checked against the runtime log.

Amp never appears on this screen because it is a terminal-only provider.

Linux browser runtime missing

The embedded browser pane on Linux uses the system WPE WebKit runtime — there is no bundled Chromium. If the required libraries are missing, the installer warns and prints the install command for your distribution. The libraries Verde looks for are:

• libWPEWebKit-2.0.so
• libWPEBackend-fdo-1.0.so
• libjavascriptcoregtk-6.0.so
• libEGL.so.1
• libGLESv2.so.2

Install them by distribution:

You can also let the installer install them by setting VERDE_INSTALL_BROWSER_DEPS=1 before running it:

curl -fsSL https://verdeai.dev/install.sh | VERDE_INSTALL_BROWSER_DEPS=1 sh

WebView2 on Windows

Windows native-webview builds use Microsoft WebView2. Windows systems that do not include WebView2 need the Microsoft WebView2 Runtime installed separately, and packaged builds must ship or locate WebView2Loader.dll next to verde.exe or on the DLL search path. The Windows native-webview build also requires the Microsoft WebView2 SDK headers at compile time.

Design Mode has no screenshot

The element and region selector works with WPE WebKit on Linux, WKWebView on macOS, and WebView2 on Windows. Selection screenshots currently require the Linux WPE backend's frame-copy support. On macOS and Windows, Verde sends the instruction and DOM context without an image; this is expected. See Design Mode for routing details.

Update check or install fails

Open Settings → Updates and choose Check now again. Update checks and installers need access to GitHub release metadata and assets. If the in-app flow still fails, run:

verde update --json

The JSON error is suitable for scripts and issue reports. Standalone Linux/macOS installs need curl; Windows uses PowerShell. A verde-bin installation owned by pacman needs either yay or paru, and the in-app flow opens that helper in a terminal pane. You can always use the install command on the homepage to replace a standalone installation manually.

Source-build errors

Source builds require Zig 0.16.0 and SDL3 development files for your platform. The default browser backend uses the host platform webview instead of bundled Chromium. Linux builds also require WPE WebKit development packages. The supported invocation from the repo root is:

mise run build

If you must call the build directly:

zig build --release=safe -Dbrowser-backend=native_webview

Common pitfalls:

• Bare zig build does not compile. It defaults to Debug + the WPE verde-browser-linux helper, which trips a vendored packages/ghostty/.../osc.zig comptime @sizeOf assertion and a crt1.o linker error. Always pass --release=safe -Dbrowser-backend=native_webview, or use mise run build.
• Running zig build from packages/desktop. That installs to packages/desktop/zig-out, not the top-level zig-out/bin/verde the app launches from. Always build from the repo root.
• CEF fallback. CEF is still available as an explicit fallback if you need the legacy Chromium backend:
  bash

  mise run build-cef
  # or
  zig build --release=safe -Dbrowser-backend=cef -Dcef-sdk-path=/path/to/cef

For release-style local installs, use the packaged install scripts:

bash ./scripts/release/install-linux-local.sh
./scripts/release/install-macos-local.sh

Reading the runtime logs

Verde writes runtime logs under SDL's platform pref path. On Linux, the usual paths are:

• ~/.local/share/verde/Native/logs/verde.stderr.log
• ~/.local/share/verde/Native/logs/last-crash.log

Those files capture Zig panic output, provider helper stderr, and the last panic marker written before the app aborted. If the app crashes, the last-crash.log is the single best place to start.

Discover the exact pref path on your machine:

verde state path --json

Inspecting the live app

While the app is running, you can inspect a lot without touching the UI:

verde live status --json | jq '.result.browser'
verde live panes --project current --json
verde live processes --json
verde live inspect --focused --json

Exit code 3 means the live server is not running or not ready — start the app first. See CLI reference for the full command surface and exit codes.

Getting help

• GitHub issues for bugs and feature requests.
• CLI reference and Configuration & state for the full programmatic surface.
• Provider setup for provider-specific setup and authentication.