zellij-org/zellij · error

failed to build forward-timeout runtime

Error message

failed to build forward-timeout runtime

What it means

Error "failed to build forward-timeout runtime" thrown in zellij-org/zellij.

Solutions

1. Check system resources (threads, memory); tokio runtime creation failed at the OS level.
2. Retry; if persistent, report with OS and resource limit details.

When it happens

Trigger: Occurs at zellij-client/src/stdin_ansi_parser.rs:903 when the operation fails: "failed to build forward-timeout runtime". Currently there is no defensive handling preventing or contextualizing this failure before it surfaces.

Common situations: Resource exhaustion or restrictive ulimits/namespace settings.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

AI-assisted analysis of zellij-org/zellij@e839bfffa5 (2026-08-19). Data as JSON: /api/errors/6f4f7ac5c06dac54. Report an issue: GitHub.

Appendix: source

Thrown at zellij-client/src/stdin_ansi_parser.rs:912

// Forward-slot timeout infrastructure
// =====================================================================

use std::sync::{Arc, Mutex, OnceLock};

/// Dedicated, lazily-initialised runtime for driving forward-slot
/// timeouts. A single current-thread executor runs on its own OS
/// thread; timer tasks are `spawn`-ed onto it from the synchronous
/// `ClientInstruction::ForwardQueryToHost` handler. One-thread model
/// because timer tasks do no CPU work — they just sleep and perform a
/// millisecond-scale mutex check on wake-up.
static FORWARD_TIMEOUT_RUNTIME: OnceLock<Arc<tokio::runtime::Runtime>> = OnceLock::new();

pub fn forward_timeout_runtime() -> &'static Arc<tokio::runtime::Runtime> {
    FORWARD_TIMEOUT_RUNTIME.get_or_init(|| {
        let rt = tokio::runtime::Builder::new_current_thread()
            .enable_time()
            .build()
            .expect("failed to build forward-timeout runtime");
        let rt = Arc::new(rt);
        let rt_for_driver = rt.clone();
        // `block_on(pending())` keeps the executor loop alive forever
        // on this thread; spawned timer tasks are polled as they
        // become ready (on spawn, on wake from the time driver).
        std::thread::Builder::new()
            .name("zellij-client-forward-timeout".into())
            .spawn(move || {
                rt_for_driver.block_on(std::future::pending::<()>());
            })
            .expect("failed to spawn forward-timeout driver thread");
        rt
    })
}

/// Spawn a timer task that closes a forward slot after `deadline` and
/// invokes `on_timeout(token, reply_bytes)` with whatever the slot
/// accumulated. Token-guard idempotent: if the barrier (or a

View on GitHub (pinned to e839bfffa5)