espanso/espanso · error

unable to start IPC handler

Error message

unable to start IPC handler

What it means

initialize_and_spawn spawns a 'daemon-ipc-handler' thread whose body calls server.run(handler). If run fails to start serving IPC requests, the expect panics inside that thread with this message, so the daemon's IPC endpoint never comes up even though initialize_and_spawn itself returned Ok.

Source

Thrown at espanso/src/cli/daemon/ipc.rs:54

                .run(Box::new(move |event| match event {
                    IPCEvent::Exit => {
                        if let Err(err) = exit_notify.send(DAEMON_SUCCESS) {
                            error!(
                "experienced error while sending exit signal from daemon ipc handler: {err}"
              );
                        }

                        EventHandlerResponse::NoResponse
                    }
                    unexpected_event => {
                        warn!(
                            "received unexpected event in daemon ipc handler: {unexpected_event:?}"
                        );

                        EventHandlerResponse::NoResponse
                    }
                }))
                .expect("unable to start IPC handler");
        })?;

    Ok(())
}

View on GitHub (pinned to e6c3736675)

Solutions

1. Ensure the runtime directory (and socket file) are not deleted while the daemon runs
2. Check that the sandbox/container permits Unix socket listen/accept operations
3. Restart the daemon so the IPC server is recreated cleanly
4. Wrap server.run with error logging instead of expect so the failure is visible in logs

Example fix

// before
.expect("unable to start IPC handler");
// after
if let Err(err) = server.run(Box::new(move |event| { /* ... */ })) {
    error!("unable to start IPC handler: {err}");
}

if !runtime_dir.is_dir() {
    eprintln!("runtime dir vanished before IPC handler start");
}

if let Err(err) = server.run(Box::new(handler)) {
    error!("IPC handler failed to start: {err}");
    exit_notify.send(WORKER_ERROR_EXIT_NO_CODE);
}

When it happens

Trigger: IPCServer::run returns Err while starting to accept connections: the IPC transport (socket/pipe) is unusable at run time, the handler channel binding fails, or runtime resources were invalidated between server creation and run.

Common situations: Runtime dir/socket removed after server creation, IPC transport not supported in the sandbox/container, OS-level socket errors during accept setup.

Related errors

• Worker process is not running, please start Espanso first.
• Worker process is not running, please start Espanso first.
• unable to initialize ipc server for daemon
• Unable to spawn worker monitor thread
• unable to spawn IPC server

AI-assisted analysis of espanso/espanso@e6c3736675 (2026-09-06). Data as JSON: /api/errors/90a516d02aa0ce15. Report an issue: GitHub.