## TL;DR
The task run exceeded its configured timeout, which means it is either genuinely slow or stuck waiting on something that will never arrive. Check the task logs to see whether it was progressing or hanging, then set the timeout from measured durations: above the worst normal case, below forever. A timeout that fires on normal work is misconfigured, not protective.

```text
prefect task run timed out after 10 minutes
```

## Use this when
- A Prefect task run times out.
- The same task sometimes finishes just under the timeout.
- A task that used to be fast now takes longer.

## Not for this skill when
- The whole flow times out. Check flow-level timeout settings.
- The task hangs with no timeout configured. Add one first.

## Steps
1. Read the task run logs up to the timeout: was it progressing or stuck? Note the behavior. Verify: slow versus stuck is decided
2. Measure the task's real duration distribution from history. Note the worst normal case. Verify: the baseline is known
3. If stuck, fix the hang: the downstream it waits on, the deadlock, the missing input. Note the hang is resolved. Verify: the hang is fixed, not papered over
4. If slow, set the timeout above the worst normal duration with headroom. Note the new value and its justification. Verify: the timeout fits reality
5. Re-run and confirm the task completes inside the timeout. Note the run is green. Verify: the fix is verified

## Variant phrasings
### prefect task timeout configuration
The config-shaped search.
### prefect task run timeout increase
The tuning phrasing.

Compatibility: Prefect 2.x task run timeouts. Timeout is set per task run; defaults apply when unset.

## Why it happens
Timeouts are a correctness tool: they turn an infinite hang into a finite failure. But a timeout value is a claim about how long the work should take, and claims need evidence. The default 10 minutes fits many tasks and none of the slow ones. When a task's real duration creeps past the default, the timeout starts killing healthy work, which looks like flakiness but is really a stale configuration. Measure first, then set.

## Edge cases / pitfalls
- Raising the timeout on a truly stuck task just delays the failure. Distinguish stuck from slow before tuning.
- Timeouts on tasks that hold locks or transactions can leave resources held. Ensure cleanup runs on timeout.
- A task that times out and retries can double-apply side effects. Make timed-out tasks idempotent or guard the retry.
- Flow-level and task-level timeouts interact: the flow timeout can kill the task first. Check both when tuning.

## Provenance

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