{"record":{"id":"d138a7913c4e5653","repo":"tokio-rs/tokio","slug":"failed-building-the-runtime","errorCode":null,"errorMessage":"Failed building the Runtime","messagePattern":"Failed building the Runtime","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"tokio-macros/src/entry.rs","lineNumber":518,"sourceCode":"        quote! {\n            #[::core::prelude::v1::test]\n        }\n    } else {\n        quote! {}\n    };\n\n    let body_ident = quote! { body };\n    // This explicit `return` is intentional. See tokio-rs/tokio#4636\n    let last_block = quote_spanned! {last_stmt_end_span=>\n\n        #[allow(clippy::expect_used, clippy::diverging_sub_expression, clippy::needless_return, clippy::unwrap_in_result)]\n        {\n            #use_builder\n\n            return #rt\n                .enable_all()\n                .#build\n                .expect(\"Failed building the Runtime\")\n                .block_on(#body_ident);\n        }\n\n    };\n\n    let body = input.body();\n\n    // For test functions pin the body to the stack and use `Pin<&mut dyn\n    // Future>` to reduce the amount of `Runtime::block_on` (and related\n    // functions) copies we generate during compilation due to the generic\n    // parameter `F` (the future to block on). This could have an impact on\n    // performance, but because it's only for testing it's unlikely to be very\n    // large.\n    //\n    // We don't do this for the main function as it should only be used once so\n    // there will be no benefit.\n    let output_type = match &input.sig.output {\n        // For functions with no return value syn doesn't print anything,","sourceCodeStart":500,"sourceCodeEnd":536,"githubUrl":"https://github.com/tokio-rs/tokio/blob/625954f365727668cb02d04172b34f1149637728/tokio-macros/src/entry.rs#L500-L536","documentation":"The #[tokio::main] / #[tokio::test] macro generates a .expect(\"Failed building the Runtime\") call on the runtime builder. It panics at process startup if Builder::build() returns Err — e.g. invalid worker/thread counts or platform runtime construction failure.","triggerScenarios":"Using #[tokio::main(flavor = \"...\", worker_threads = N, ...)] with parameters Builder rejects; calling #[tokio::main] on a platform where runtime construction is unsupported.","commonSituations":"Setting worker_threads = 0; using start_paused without current-thread flavor; wasm/wasi targets lacking full runtime support; build options incompatible with the chosen flavor.","solutions":["Set worker_threads >= 1 (or omit it for the default).","Match macro flavor with options: start_paused and a multi-thread flavor are incompatible.","Construct the runtime manually with Builder::new_*().build() to surface the real error instead of an expect panic.","Check target platform support for the runtime features requested."],"exampleFix":"// before\n#[tokio::main(flavor = \"multi_thread\", worker_threads = 0)]\nasync fn main() {}\n// after\n#[tokio::main(flavor = \"multi_thread\", worker_threads = 1)]\nasync fn main() {}","handlingStrategy":"validation","validationCode":"// Build the runtime manually to surface the real error instead of an expect panic:\nlet rt = tokio::runtime::Builder::new_multi_thread()\n    .worker_threads(2)\n    .enable_all()\n    .build()?; // returns Result","typeGuard":null,"tryCatchPattern":"// Macro path panics; switch to manual build to catch:\nmatch tokio::runtime::Builder::new_multi_thread().enable_all().build() {\n    Ok(rt) => rt.block_on(main_async()),\n    Err(e) => { eprintln!(\"runtime build failed: {e}\"); std::process::exit(1); }\n}","preventionTips":["Use worker_threads >= 1.","Don't combine incompatible Builder options (e.g. start_paused with multi_thread).","Prefer manual Builder over the macro when you need error handling at startup."],"tags":["runtime","macro","tokio-main","panic","startup"],"backgroundTag":null,"analyzedSha":"625954f365727668cb02d04172b34f1149637728","analyzedAt":"2026-08-11T17:46:45.378Z","contentChangedAt":"2026-08-11T17:46:45.378Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}