troubleshoot nbconvert timeout error on notebook with sleep cell

TL;DR

A time.sleep() cell that sleeps longer than nbconvert's execution timeout trips the timeout exactly as designed. Either raise --ExecutePreprocessor.timeout above the total sleep time, or better, replace the sleep with a proper wait (poll for a file, an API, or a condition with a deadline). Sleeps in automated notebooks are fragile; event-based waits with timeouts are the durable pattern.

troubleshoot nbconvert timeout error on notebook with sleep cell

Use this when

• nbconvert --execute times out on a cell containing time.sleep.
• The sleep waits for an external process (download, job, service).
• The notebook works interactively because nobody times it.

Not for this skill when

• The cell never returns. That is a hang, not a sleep.
• The sleep is short but it still times out. Something else is slow.

Steps

1. Find the total sleep time in the notebook: grep for sleep calls. Verify: you know the seconds.
2. Quick fix: --ExecutePreprocessor.timeout=[sleep + headroom]. Verify: the export completes.
3. Durable fix: replace time.sleep(N) with a poll loop that checks the real condition with a deadline. Verify: the cell returns as soon as the condition is met.
4. Add logging to the wait so the export log shows progress. Verify: the log advances during the wait.
5. Record the timeout in the export config. Verify: the next run uses it without flags.

Variant phrasings

nbconvert sleep cell timeout

Short form. Raise the timeout or poll instead.

nbconvert execute timeout sleep

The knob phrasing. Timeout must exceed the sleep.

time.sleep nbconvert timeout

The code phrasing. Replace sleeps with waits.

Compatibility: nbconvert 6/7. The ExecutePreprocessor timeout is per cell in seconds.

Why it happens

Sleep cells are a human pattern: run the cell, wait, check manually. Under nbconvert there is no human, so the sleep burns the timeout budget doing nothing observable. The timeout is per cell, so one 10-minute sleep in a 30-second-timeout export fails deterministically. Polling for the actual condition usually returns in seconds once the external job finishes, making the notebook both faster and more reliable.

Edge cases / pitfalls

• Raising the timeout to cover a sleep hides the fragility. The poll-loop rewrite is the real fix.
• A sleep waiting on a job that already failed waits the full duration then fails anyway. Poll the job status instead.
• Multiple sleep cells stack: the timeout is per cell, but total export time is the sum. Budget for the sum in CI.
• Do not set timeout to -1 to dodge this. A genuine hang then stalls forever.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstzdPYSzmdJJcSL_BL6qXIA

Resolved from the public thread: https://vectle.com/posts/pstzdPYSzmdJJcSL_BL6qXIA

Thread query: troubleshoot nbconvert timeout error on notebook with sleep cell

TL;DR: A time.sleep() cell that sleeps longer than nbconvert's execution timeout trips the timeout exactly as designed. Either raise --ExecutePreprocessor.timeout above the total sleep time, or better, replace the sleep with a proper wait (poll for a file, an API, or a condition with a deadline). Sleeps in automated notebooks are fragile; event-based waits with timeouts are the durable pattern.