What causes "Unable to start Tokio async runtime" in gleam-lang/gleam?

Raise thread/process limits (`ulimit -u`, container pids limit)

Unable to start Tokio async runtime

Error message

Unable to start Tokio async runtime

What it means

`gleam hex retire` (compiler-cli/src/hex.rs:39) starts a Tokio runtime to authenticate and call `hex::retire_release`. If `tokio::runtime::Runtime::new()` cannot create its worker threads or IO/time driver descriptors, the `.expect("Unable to start Tokio async runtime")` panics and the command exits before any Hex API call is made.

Source

Thrown at compiler-cli/src/hex.rs:39

    match credentials {
        hexpm::Credentials::ApiKey(key) => Ok(hexpm::WriteActionCredentials::ApiKey(key.clone())),
        hexpm::Credentials::OAuthAccessToken(token) => {
            let one_time_password = cli::ask("Enter your two-factor authentication code")?.into();
            Ok(hexpm::WriteActionCredentials::OAuthAccessToken {
                access_token: token.clone(),
                one_time_password,
            })
        }
    }
}

pub fn retire(
    package: String,
    version: String,
    reason: RetirementReason,
    message: Option<String>,
) -> Result<()> {
    let runtime = tokio::runtime::Runtime::new().expect("Unable to start Tokio async runtime");
    let config = hexpm::Config::new();
    let http = HttpClient::new();
    let credentials =
        HexAuthentication::new(&runtime, &http, config.clone()).get_or_create_api_credentials()?;

    runtime.block_on(hex::retire_release(
        &package,
        &version,
        reason,
        message.as_deref(),
        &write_credentials(&credentials)?,
        &config,
        &http,
    ))?;
    cli::print_retired(&package, &version);
    Ok(())
}

View on GitHub (pinned to 7e623aa83d)

Solutions

Raise thread/process limits (`ulimit -u`, container pids limit)
Raise fd limits (`ulimit -n 4096`) and fix fd leaks
Ensure memory headroom for runtime threads
Allow Tokio's syscalls (`clone`, `epoll_create1`, `eventfd`, `timerfd_*`) in seccomp/AppArmor
Retry `gleam hex retire` after the environment is fixed

Example fix

# before: panics 'Unable to start Tokio async runtime'

# after: run with sane limits in the release job
bash -c 'ulimit -n 4096; gleam hex retire mypkg 1.0.0 --reason invalid'

Defensive patterns

Strategy: validation

Validate before calling

# retire with limits fixed inline
bash -c 'ulimit -n 4096; gleam hex retire "$0" "$1" --reason other' "$PKG" "$VER"

Prevention

Run hex maintenance commands from the same CI environment used for publishing
Pre-authenticate and store credentials so maintenance runs need fewer moving parts

When it happens

Trigger: Running `gleam hex retire <pkg> <ver> --reason ...` where thread creation or epoll/timerfd creation fails: `ulimit -u`/cgroup pids limits, `ulimit -n` exhaustion, no memory for thread stacks, or sandboxed syscalls blocked.

Common situations: Release-maintenance automation in capped containers; CI agents whose fd table is full from earlier steps; minimal scratch/distroless images with restrictive defaults.

Related errors

AI-assisted analysis of gleam-lang/gleam@7e623aa83d (2026-08-17). Data as JSON: /api/errors/221e15bb8a965c8a. Report an issue: GitHub.