## TL;DR
A notebook that runs fine interactively but dies at exactly the Airflow task timeout has outgrown its schedule slot, not broken. Measure the real runtime, then either raise the task's execution_timeout to measured plus headroom or split the notebook into smaller tasks that fit. Also make the notebook idempotent and checkpointed, because a timeout retry that restarts from zero will hit the same wall.

```text
agent's scheduled notebook run timed out at the 2-hour airflow timeout
```

## Use this when
- A scheduled papermill/nbconvert task fails at exactly the timeout, every run.
- The notebook completes given more time (manual run).
- The notebook has grown over weeks of added cells.

## Not for this skill when
- The task fails fast. That is a bug, not a budget.
- The task hangs (never finishes). That is a hang, not a slow run.

## Steps
1. Measure the true runtime with a manual or one-off run. Verify: you have a number, not a guess.
2. Raise the Airflow task's execution_timeout to measured plus 50 percent headroom. Verify: the DAG parses and the timeout is set.
3. Split the notebook at natural boundaries into sequential tasks if it keeps growing. Verify: each task fits comfortably in its budget.
4. Make each piece idempotent with checkpoints. Verify: a retry resumes instead of restarting.
5. Monitor runtimes over weeks. Verify: you get warned before the next timeout, not after.

## Variant phrasings
### airflow notebook timeout 2 hours
Short form. Measure, raise, or split.

### scheduled notebook exceeds timeout
General phrasing. Budget from measured runtimes.

### papermill airflow execution timeout
The stack phrasing. Same timeout economics.

Compatibility: Airflow 2.x with papermill or nbconvert operators. execution_timeout is per task.

## Why it happens
Timeouts are set once when the DAG is written and the notebook grows forever after, so the collision is a matter of time. Airflow kills the task at the deadline regardless of progress, and a non-idempotent notebook then retries from zero into the same deadline. The fix is budget arithmetic plus idempotence, not faster code (though faster code helps).

## Edge cases / pitfalls
- Raising the timeout without idempotence makes retries expensive instead of impossible. Do both.
- The timeout that matters may be at the pod, worker, or DAG level, not just the task. Check all of them.
- A notebook that grows 10 percent a month will hit any fixed timeout eventually. Split before you must.
- Log per-cell timings in the scheduled run. The next timeout investigation starts there.

## Provenance

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