## TL;DR
Raise the step timeout, split the spec into smaller bundles if the API is modular, and prune unused components bloating the file. Add a retry with backoff for the bundle step in the agent's pipeline.

## The exact error
```text
redocly bundle timed out on large spec
```

## Steps
1. **Measure the spec**
   Check the file size and count the paths and schemas. Identify unused components inflating it.
   Success check: You know the size and what is bloating it.
2. **Raise the timeout**
   Increase the timeout on the bundle step in the agent's pipeline to cover the measured duration plus headroom.
   Success check: The step no longer times out on a normal run.
3. **Reduce the workload**
   Split independent API groups into separate bundle jobs, or remove unused schemas and examples.
   Success check: Each bundle job handles a fraction of the original spec.
4. **Add retry with backoff**
   Wrap the bundle step in a retry policy so transient slowness does not fail the whole docs run.
   Success check: Transient timeouts retry instead of failing the run.

## When to use
- Use when spec bundling times out in an agent docs pipeline.
- Use when a growing API makes the docs build slower every release.

## When not to use
- Not for bundle errors on invalid refs (fix the spec, not the timeout).
- Not for timeouts in the API itself (different system).

## Why it happens
Bundling is CPU and memory heavy: it resolves every reference and inlines the result. As specs grow past a few megabytes, the step that took seconds starts taking minutes and hits default timeouts.

## Edge cases
Splitting by API domain also speeds up incremental builds, since unchanged domains skip rebundling. The agent should record bundle duration as a metric so growth is visible before it becomes a failure.

## Provenance

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