gleam-lang/gleam · critical

Unable to start Tokio async runtime

Error message

Unable to start Tokio async runtime

What it means

`gleam docs remove` (compiler-cli/src/docs.rs:25) builds a Tokio runtime to authenticate with Hex and send the docs-removal API request. `tokio::runtime::Runtime::new()` fails when the OS denies worker-thread creation or the epoll/timerfds for its drivers; `.expect("Unable to start Tokio async runtime")` then panics, aborting the command before credentials are even read.

Source

Thrown at compiler-cli/src/docs.rs:25

use ecow::EcoString;

use crate::{cli, fs::ProjectIO, http::HttpClient};
use gleam_core::{
    Result,
    analyse::TargetSupport,
    build::{Codegen, Compile, Mode, Options, Package, Target},
    config::{DocsPage, PackageConfig},
    docs::{Dependency, DependencyKind, DocContext},
    error::Error,
    hex,
    io::HttpClient as _,
    manifest::ManifestPackageSource,
    paths::ProjectPaths,
    type_,
};

pub fn remove(package: String, version: String) -> Result<()> {
    let runtime = tokio::runtime::Runtime::new().expect("Unable to start Tokio async runtime");
    let http = HttpClient::new();
    let hex_config = hexpm::Config::new();
    let credentials = crate::hex::HexAuthentication::new(&runtime, &http, hex_config.clone())
        .get_or_create_api_credentials()?;

    // Remove docs from API
    let request = hexpm::api_remove_docs_request(
        &package,
        &version,
        &crate::hex::write_credentials(&credentials)?,
        &hex_config,
    )
    .map_err(Error::hex)?;
    let response = runtime.block_on(http.send(request))?;
    hexpm::api_remove_docs_response(response).map_err(Error::hex)?;

    // Done!
    println!("The docs for {package} {version} have been removed from HexDocs");

View on GitHub (pinned to 7e623aa83d)

Solutions

  1. Raise `ulimit -u`/pids limits so Tokio can spawn its worker pool
  2. Raise `ulimit -n` (e.g. 4096) and clear fd leaks
  3. Add memory headroom or raise the container memory cap
  4. Permit `clone`/`epoll_create1`/`eventfd`/`timerfd_*` in custom seccomp
  5. Retry `gleam docs remove` once the environment allows a runtime

Example fix

# before: panics at startup
docker run --pids-limit 16 ci gleam docs remove --package mypkg --version 1.0.0

# after: adequate pids headroom
docker run --pids-limit 512 ci gleam docs remove --package mypkg --version 1.0.0
Defensive patterns

Strategy: validation

Validate before calling

# before running docs removal in automation
ulimit -n 4096
gleam docs remove --package "$PKG" --version "$VER"

Prevention

When it happens

Trigger: Running `gleam docs remove --package <name> --version <ver>` on a host where `Runtime::new()` cannot be built: thread/process limits (`ulimit -u`, cgroup pids.max), fd exhaustion (EMFILE), no memory for thread stacks, or a seccomp profile blocking `clone`/`epoll_create1`.

Common situations: Release automation in tightly capped containers (`--pids-limit`, low nofile); CI images with dozens of concurrent jobs exhausting the process limit; hardened runners denying eventfd/epoll syscalls.

Related errors

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