helix-editor/helix · error

Failed to start debug client: {}

Error message

Failed to start debug client: {}

What it means

After resolving a debugger config, helix spawns the adapter process named by its `command` field via Editor::debug_adapters.start_client. If the executable is not found on PATH or spawning fails, the cause is wrapped as 'Failed to start debug client: <err>'. The failure happens at process creation, before any DAP handshake.

Source

Thrown at helix-term/src/commands/dap.rs:143

        .editor
        .workspace_trust
        .query(&workspace, helix_loader::workspace_trust::TrustQuery::Dap)
        .is_trusted()
    {
        bail!("Workspace is not trusted. Run `:workspace-trust` to enable the debug adapter.");
    }

    let doc = doc!(cx.editor);
    let config = doc
        .language_config()
        .and_then(|config| config.debugger.as_ref())
        .ok_or_else(|| anyhow!("No debug adapter available for language"))?;

    let id = cx
        .editor
        .debug_adapters
        .start_client(socket, config)
        .map_err(|e| anyhow!("Failed to start debug client: {}", e))?;

    // TODO: avoid refetching all of this... pass a config in
    let template = match name {
        Some(name) => config.templates.iter().find(|t| t.name == name),
        None => config.templates.first(),
    }
    .ok_or_else(|| anyhow!("No debug config with given name"))?;

    let mut args: HashMap<&str, Value> = if let Some(params) = params.as_ref() {
        let preprocessed_params = prepare_dap_params(template, params);
        template
            .args
            .iter()
            .map(|(k, v)| (k.as_str(), map_value(v, &preprocessed_params)))
            .collect()
    } else {
        template
            .args

View on GitHub (pinned to 079a789e8c)

Solutions

1. Verify helix can see the binary in its environment: `:sh which <command>` (or run `which` from the same shell/launcher).
2. Update `command` in the debugger config to the name that exists, or use an absolute path to the adapter binary.
3. Install the adapter and fully restart helix so the spawn environment is refreshed.

Example fix

# before
[language.debugger]
command = "lldb-vscode"
# after
[language.debugger]
command = "/usr/bin/lldb-dap"

// confirm the adapter resolves on PATH before starting a session
if which::which(&dbg.command).is_err() {
    // tell the user to install it / fix `command` before :debug-start
}

if let Err(e) = dap_start_impl(cx, name, addr, args) {
    cx.editor.set_error(format!("debug: {e}")); // keep editing; cause names the spawn failure
}

When it happens

Trigger: languages.toml debugger `command = "lldb-vscode"` while only `lldb-dap` is installed (LLVM 17+ renamed the binary); adapter installed but not on helix's PATH (launched from a GUI); codelldb installed only as a VSCode extension.

Common situations: Adapter binary renames across toolchain versions; PATH differences between terminal and desktop launcher environments; adapters bundled inside other tools' directories.

Related errors

• Command not provided
• Incorrect transport {}
• DAP request failed
• No debug adapter available for language
• No debug config with given name

AI-assisted analysis of helix-editor/helix@079a789e8c (2026-08-16). Data as JSON: /api/errors/09dc38d562b5b0df. Report an issue: GitHub.