docs agent failed: redocly bundle timed out on a 3MB openapi spec
Fixes a docs agent whose Redocly bundle step times out on a large OpenAPI spec. The skill shows how to raise the timeout, split the bundle work, and reduce the spec size the bundler must hold in memory. It gives the agent a retry policy for heavyweight doc artifacts.
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 specSteps
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.
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.
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.
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