{"record":{"id":"97eb355760734c2a","repo":"rwf2/Rocket","slug":"create-tokio-runtime","errorCode":null,"errorMessage":"create tokio runtime","messagePattern":"create tokio runtime","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"core/lib/src/lib.rs","lineNumber":237,"sourceCode":"\n/// Creates a [`Rocket`] instance with a custom config provider: aliases\n/// [`Rocket::custom()`].\npub fn custom<T: figment::Provider>(provider: T) -> Rocket<Build> {\n    Rocket::custom(provider)\n}\n\n/// WARNING: This is unstable! Do not use this method outside of Rocket!\n#[doc(hidden)]\npub fn async_run<F, R>(fut: F, workers: usize, sync: usize, force_end: bool, name: &str) -> R\n    where F: std::future::Future<Output = R>\n{\n    let runtime = tokio::runtime::Builder::new_multi_thread()\n        .thread_name(name)\n        .worker_threads(workers)\n        .max_blocking_threads(sync)\n        .enable_all()\n        .build()\n        .expect(\"create tokio runtime\");\n\n    let result = runtime.block_on(fut);\n    if force_end {\n        runtime.shutdown_timeout(std::time::Duration::from_millis(500));\n    }\n\n    result\n}\n\n/// WARNING: This is unstable! Do not use this method outside of Rocket!\n#[doc(hidden)]\npub fn async_test<R>(fut: impl std::future::Future<Output = R>) -> R {\n    async_run(fut, 1, 32, true, &format!(\"{WORKER_PREFIX}-test-thread\"))\n}\n\n/// WARNING: This is unstable! Do not use this method outside of Rocket!\n#[doc(hidden)]\npub fn async_main<R>(fut: impl std::future::Future<Output = R> + Send) -> R {","sourceCodeStart":219,"sourceCodeEnd":255,"githubUrl":"https://github.com/rwf2/Rocket/blob/3a54d079aef060a8f732bd04ea54b0581a604087/core/lib/src/lib.rs#L219-L255","documentation":"Rocket launches on a dedicated tokio multi-thread runtime built by the internal async_run helper; the .expect(\"create tokio runtime\") turns any io::Error from Builder::build() into a panic that aborts launch. build() fails when the OS cannot supply what a runtime needs: worker/blocking threads (pthread_create), thread-stack memory, or the epoll/eventfd file descriptors for the I/O and time drivers enabled by .enable_all(). It signals a process or environment resource limit, not a mistake in your Rocket application code.","triggerScenarios":"Calling rocket.launch() or #[rocket::main] when the process has hit its thread budget (ulimit -u, cgroup pids.max, Docker --pids-limit); running with so few spare file descriptors that epoll/eventfd creation fails with EMFILE; running under a seccomp/gVisor sandbox that blocks clone/epoll_create/eventfd syscalls; heavy memory pressure failing thread-stack allocation; launching multiple Rocket instances concurrently so each async_run build competes for the remaining thread/fd quota. Rocket's default worker count is num_cpus, so many-core hosts inside small pids-limited containers are the classic trigger.","commonSituations":"Containerized deploys (Docker/Kubernetes) with low default pids limits on many-core hosts where workers = num_cpus exceeds the cap; CI runners with syscall filters; migrating from Rocket 0.4 to 0.5, where launch now builds a full tokio runtime on hosts that previously restricted threading; hosts under memory exhaustion where thread stacks cannot be allocated.","solutions":["Raise the thread budget where the process runs: increase Docker --pids-limit / cgroup pids.max or ulimit -u so Rocket's worker threads plus blocking threads fit with headroom.","Pin the worker count below the limit in Rocket.toml with [default] workers = 4 instead of the num_cpus default.","Check file-descriptor headroom (ulimit -n, systemd LimitNOFILE) — the tokio I/O driver needs spare fds for epoll/eventfd.","If a sandbox (gVisor, seccomp profile) blocks clone/epoll_create/eventfd, allow those syscalls or run the service outside the filter.","Relieve memory pressure and avoid launching multiple Rocket instances simultaneously, since each launch builds its own runtime via async_run."],"exampleFix":"# before — 64-core host, container capped at 32 pids; Rocket defaults to\n# workers = num_cpus (64 threads) and panics at launch: 'create tokio runtime'\ndocker run --pids-limit 32 my-rocket-app\n\n# after — give the runtime headroom, and/or pin workers explicitly\ndocker run --pids-limit 512 my-rocket-app\n\n# Rocket.toml\n[default]\nworkers = 4","handlingStrategy":"validation","validationCode":"fn assert_runtime_resources() -> std::io::Result<()> {\n    // proxy for tokio's worker spawn: can we still create a thread?\n    std::thread::Builder::new()\n        .stack_size(2 * 1024 * 1024)\n        .spawn(|| ())?\n        .join()\n        .map_err(|_| std::io::Error::other(\"thread join failed\"))?;\n    // proxy for the I/O driver: can we still open a file descriptor?\n    std::fs::File::open(\"/dev/null\")?;\n    Ok(())\n}\n\n// call before rocket.launch(); fail with a clear diagnostic, not a panic\nassert_runtime_resources()\n    .expect(\"not enough threads/fds to build the tokio runtime\");","typeGuard":null,"tryCatchPattern":"// supervisor pattern: keep a launch failure from tearing down the process\n// without diagnostics\nlet prev = std::panic::take_hook();\nstd::panic::set_hook(Box::new(|info| eprintln!(\"launch panicked: {info}\")));\nlet outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {\n    rocket.launch()\n}));\nstd::panic::set_hook(prev);\nif outcome.is_err() {\n    // surface environment diagnostics: /proc/self/limits, thread and fd counts\n}","preventionTips":["Set container --pids-limit and ulimit -u to at least ~2x Rocket's configured workers plus blocking-pool threads","Pin `workers` in Rocket.toml instead of relying on the num_cpus default on many-core hosts","Smoke-test the exact production image with the same limits before deploy","Monitor thread count and open-fd count of the service in production"],"tags":["rust","rocket","tokio","runtime","panic","resource-limits","docker","thread-limit"],"backgroundTag":"tokio-runtime-creation-failed","analyzedSha":"3a54d079aef060a8f732bd04ea54b0581a604087","analyzedAt":"2026-08-16T22:01:48.395Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}