tokio-rs/tokio · error · syn::Error

The `worker_threads` option requires the `multi_thread` runt

Error message

The `worker_threads` option requires the `multi_thread` runtime flavor. Use `#[{}(flavor = "multi_thread")]`

What it means

In `build` (entry.rs:200), `worker_threads` is only meaningful for the `multi_thread` flavor. If the attribute combines `current_thread` or `local` flavor with `worker_threads = N`, the macro emits this guidance pointing the user at the required flavor change.

Source

Thrown at tokio-macros/src/entry.rs:200

    }

    fn macro_name(&self) -> &'static str {
        if self.is_test {
            "tokio::test"
        } else {
            "tokio::main"
        }
    }

    fn build(&self) -> Result<FinalConfig, syn::Error> {
        use RuntimeFlavor as F;

        let flavor = self.flavor.unwrap_or(self.default_flavor);

        let worker_threads = match (flavor, self.worker_threads) {
            (F::CurrentThread | F::Local, Some((_, worker_threads_span))) => {
                let msg = format!(
                    "The `worker_threads` option requires the `multi_thread` runtime flavor. Use `#[{}(flavor = \"multi_thread\")]`",
                    self.macro_name(),
                );
                return Err(syn::Error::new(worker_threads_span, msg));
            }
            (F::CurrentThread | F::Local, None) => None,
            (F::Threaded, worker_threads) if self.rt_multi_thread_available => {
                worker_threads.map(|(val, _span)| val)
            }
            (F::Threaded, _) => {
                let msg = if self.flavor.is_none() {
                    "The default runtime flavor is `multi_thread`, but the `rt-multi-thread` feature is disabled."
                } else {
                    "The runtime flavor `multi_thread` requires the `rt-multi-thread` feature."
                };
                return Err(syn::Error::new(Span::call_site(), msg));
            }
        };

View on GitHub (pinned to 625954f365)

Solutions

1. Switch the flavor to `multi_thread` if you actually want N worker threads: `#[tokio::main(flavor = "multi_thread", worker_threads = 4)]`.
2. Or remove the `worker_threads` option if the single-threaded runtime is intended.
3. Make sure the `rt-multi-thread` feature is enabled in `Cargo.toml` once you switch to `multi_thread`.

Example fix

// before
#[tokio::main(flavor = "current_thread", worker_threads = 4)]
async fn main() {}

// after
#[tokio::main(flavor = "multi_thread", worker_threads = 4)]
async fn main() {}

When it happens

Trigger: Writing `#[tokio::main(flavor = "current_thread", worker_threads = 4)]` or `#[tokio::test(flavor = "local", worker_threads = 2)]`.

Common situations: Adding `worker_threads` while leaving the default/explicit single-threaded flavor; misunderstanding that `current_thread` ignores worker count.

Related errors

• The runtime flavor `multi_thread` requires the `rt-multi-thr
• The `start_paused` option requires the `current_thread` runt
• The `unhandled_panic` option requires the `current_thread` r
• `name` set multiple times.
• `flavor` set multiple times.

AI-assisted analysis of tokio-rs/tokio@625954f365 (2026-08-11). Data as JSON: /api/errors/2b2482ffa6d4ca20. Report an issue: GitHub.