docs agent failed: redocly bundle timed out on a 3MB openapi spec

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

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

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

Thread query: docs agent failed: redocly bundle timed out on a 3MB openapi spec

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.