actix/actix · error · panic

failed to spawn thread

Error message

failed to spawn thread

What it means

SyncArter's start_with_thread_builder panics when std::thread::Builder::spawn fails to create the sync actor's OS thread. Thread spawn failures typically come from resource exhaustion (hitting thread or memory limits) or OS-level restrictions. The .expect() makes this a hard abort of the sync actor startup.

Solutions

1. Raise the thread/process limit: ulimit -u, or container --pids-limit / cgroup pids.max.
2. Reduce the number of concurrently started sync actors, or pool them.
3. Check memory availability; lower thread stack_size if a large custom stack was configured.
4. Inspect sandbox/seccomp policies that may block clone()/pthread_create.
5. In application code, pre-check system capacity or fall back to regular (non-sync) actors.

Example fix

// before (container)
docker run --pids-limit 16 myapp

// after
docker run --pids-limit 512 myapp

// Pre-check thread capacity before starting sync actors
let limits = fs::read_to_string("/proc/self/limits")
    .map(|l| l.contains("Max processes"))
    .unwrap_or(true);
assert!(limits, "process/thread limit file unreadable — verify ulimits");

// spawn() returns io::Result; replicate the check yourself before expect
match thread_builder.spawn(worker) {
    Ok(h) => h,
    Err(e) => { log::error!("thread spawn failed: {e}"); return; }
}

When it happens

Trigger: Calling SyncArter::start / start_with_thread_builder when the OS cannot spawn a thread — process at its thread limit (ulimit -u, cgroup pids.max), out of memory for the new stack, or running in a restricted sandbox.

Common situations: Containers with low pids limits; applications spawning very large numbers of sync actors; low ulimit settings in CI or Docker; thread stack size requests too large for available memory.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Mocker actor used before set
• cannot clone `Sender` -- too many outstanding senders
• Map must not be polled after it returned `Poll::Ready`
• ActorFuture polled after finish
• Fold polled after completion

AI-assisted analysis of actix/actix@36e5d97e41 (2026-09-11). Data as JSON: /api/errors/24930a669bfb577d. Report an issue: GitHub.

Appendix: source

Thrown at actix/src/sync.rs:147

        F: Fn() -> A + Send + Sync + 'static,
        BF: FnMut() -> thread::Builder,
    {
        let factory = Arc::new(factory);
        let (sender, receiver) = cb_channel::unbounded();
        let (tx, rx) = channel::channel(0);

        for _ in 0..threads {
            let f = Arc::clone(&factory);
            let sys = System::current();
            let actor_queue = receiver.clone();
            let inner_rx = rx.sender_producer();

            thread_builder_factory()
                .spawn(move || {
                    System::set_current(sys);
                    SyncContext::new(f, actor_queue, inner_rx).run();
                })
                .expect("failed to spawn thread");
        }

        System::current().arbiter().spawn(Self {
            queue: Some(sender),
            msgs: rx,
        });

        Addr::new(tx)
    }
}

impl<A> Actor for SyncArbiter<A>
where
    A: Actor<Context = SyncContext<A>>,
{
    type Context = Context<Self>;
}

View on GitHub (pinned to 36e5d97e41)