cd /news/ai-agents/threadpoolexecutor-result-timeout-1-… · home › topics › ai-agents › article
[ARTICLE · art-173637] src=dev.to ↗ pub= topic=ai-agents verified=true sentiment=↓ negative

ThreadPoolExecutor result(timeout=1) Left 4 Calls Running

A developer's tests on CPython 3.14.4 show that ThreadPoolExecutor's future.result(timeout=1) only stops the caller from waiting, not the underlying work: four agent tool calls that each raised TimeoutError after 1 second all ran their full 5 seconds, future.cancel() returned False, and a subsequent 0.1-second call on the same pool waited 1.10 seconds for a free worker. The asyncio equivalent, asyncio.wait_for(asyncio.to_thread(...)), timed out at 1.00 second but left the thread running, and asyncio.run() did not return until 8.10 seconds because shutdown waits on the default executor's threads. The developer's fix runs each tool in a spawned child process and terminates the worker on timeout.

recommendation

Run slow, uncooperative agent tool calls in a spawned child process and terminate the worker on timeout, since ThreadPoolExecutor timeouts leave the thread running and starve the pool.

more in playbook: Designing agent systems
by read4 min views2 publishedNov 21, 2026

future.result(timeout=1) raises TimeoutError after one second, but the thread keeps running the call to the end, and future.cancel() returns False because the work already started; if a tool call must really stop, run it in a child process and terminate that process on timeout. In my test, four agent tool calls that each "timed out" after 1 s all ran their full 5 s, and the next 0.1 s call on the same pool waited 1.10 s for a free thread.

This story was written with the assistance of an AI writing program. All numbers come from CPython 3.14.4 on Linux 7.0, and both scripts ran twice with identical output.

Here is the version that actually stops the work. It is the code I now use for agent tools that wrap slow, uncooperative functions:

import multiprocessing as mp
import time
def tool(secs):
    time.sleep(secs)
    return "ok"
def run_tool(fn, *args, timeout):
    ctx = mp.get_context("spawn")
    with ctx.Pool(1) as pool:
        res = pool.apply_async(fn, args)
        return res.get(timeout=timeout)  # leaving the with-block terminates the worker

The rest of this post is why the thread version cannot do this, and what it costs you when you try.

Yesterday I wrote about subprocess.run(timeout=1) leaving orphans behind. The same question applies one layer up. A lot of agent frameworks run tool functions in a ThreadPoolExecutor so the event loop stays free, then put a timeout on the future. I wanted to know what that timeout actually does.

The test is small: a tool that sleeps 5 seconds and records when it finishes, a pool with four workers, and four calls, each awaited with result(timeout=1). Then a fresh 0.1 s call on the same pool, then the asyncio equivalent, asyncio.wait_for(asyncio.to_thread(...), timeout=1).

From the first run, unedited:

result(timeout=1): 4 TimeoutError by 4.00s, cancel()=False, running=4, threads=5
fresh 0.1s call on same pool returned after 1.10s
wait_for(to_thread, timeout=1): TimeoutError at 1.00s
asyncio.run returned at 8.10s
completed in background: [('call0', 5.0), ('call1', 5.0), ('call2', 5.0), ('call3', 5.0), ('fresh', 5.1), ('async', 8.1)]

Every timeout fired on schedule. None of them stopped anything. All four calls finished at 5.0 s and wrote their results into a list nobody was reading. If those calls had been sending emails or writing rows, all four side effects would have happened after the caller had already logged "tool timed out".

The concurrent.futures docs are honest about this: "If the call is currently being executed or finished running and cannot be cancelled then the method will return False." In other words, it removes queued work, nothing else. Python has no supported way to kill a thread. The timeout on result() is a timeout on your wait, not on the work.

That distinction is easy to miss because the exception type looks like a verdict. TimeoutError reads as "the call was stopped". It means "I stopped waiting".

The second line is the one that would hurt in production. After four timeouts the pool looked idle from the caller's side, but all four workers were still busy. A 0.1 s call submitted at that point sat in the queue until a worker came free at the 5 s mark and returned after 1.10 s.

Scale that up. An agent that retries a slow tool a few times can fill the pool with zombie calls, and then every fast tool queues behind them. Nothing errors. Latency just climbs, and the traces show "timeout" on the slow calls and "slow" on the fast ones, which points you at the wrong thing.

asyncio.wait_for(asyncio.to_thread(tool, 3), timeout=1) raised at 1.00 s, as advertised. The thread kept going. Then asyncio.run() itself did not return until 8.10 s, because on shutdown it waits for the default executor's threads to finish. So the "1 second" timeout turned into a 2 s stall at exit, well after the caller moved on. In a CLI agent that is the "why does it hang after printing the answer" bug.

The fix at the top swaps the thread for a one-worker process pool. On timeout, leaving the with block calls terminate() on the worker, so the work really ends. Its output, twice:

TimeoutError at 1.04s, children left: 0
ok 0.16s

The price is about 0.15 s of spawn start-up per call and the usual pickling rules for arguments and results. For tools that call slow external code, that is cheap. For tools that are just HTTP requests, a better fix is a real timeout inside the call, such as an httpx timeout or asyncio.timeout around an async client, because cooperative cancellation never leaves a half-done write behind a killed process.

future.result(timeout=N) and asyncio.wait_for(to_thread(...)) time out your wait, not the work. The function runs to completion.future.cancel() returns False once the call has started. Do not treat it as a kill switch.asyncio.run() waits for executor threads at exit, so a timed-out thread can stall shutdown.

── more in #ai-agents 4 stories · sorted by recency
── more on @threadpoolexecutor 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/threadpoolexecutor-r…] indexed:0 read:4min 2026-11-21 · —