docs agent failed: timed out waiting for docusaurus dev server to start

docs agent failed: timed out waiting for docusaurus dev server to start

TL;DR

Time a manual start to learn how long it really takes, clear the usual blockers like stale cache and occupied ports, then raise the agent's wait to a multiple of the measured time. Docusaurus cold starts on big sites can take minutes; the agent's default wait gives up before the ready message ever prints.

The error

docs agent failed: timed out waiting for docusaurus dev server to start

Steps

1. Time a manual start and watch for the success message:

time npm run start

Expected: you know the real startup time on this machine with this site.

1. Clear the common blockers. Remove the stale build cache, confirm the port is free, and check the node version meets the site's requirement:

rm -rf .docusaurus

Expected: no stale-cache errors and no port-in-use failure in the output.

1. Raise the agent's startup timeout to 2 to 3 times the measured time, and make it wait for the ready log line rather than a fixed sleep.

Expected: the agent proceeds only after the server is actually up.

1. For repeated runs, keep one warm server alive across tasks instead of restarting per task.

Expected: later tasks skip the cold start entirely and the timeout never comes into play.

Use this when

• the agent gives up on the dev server before it is ready, but a manual start works
• timeouts started as the site grew with more pages, versions, or locales
• the agent uses a fixed sleep instead of waiting for the ready message

Not for this skill when

• the dev server crashes with an error instead of starting slowly
• the failure is in the production build, not the dev server
• the server starts fast by hand too (look for an environment difference)

Variant phrasings

docusaurus start too slow for agent timeout

Measure first; the fix is a longer wait, not a faster start.

dev server never ready in automation

Wait on the ready log line, not on a timer.

agent cannot reach docusaurus dev server

Distinguish slow start (this skill) from port-in-use or crash (different fixes).

Why it happens

Cold starts compile the whole site: every page, version, and locale. Agents with short fixed waits poll a server that is not listening yet, declare failure, and sometimes leave a half-started process holding the port for the next attempt.

Edge cases

• A port held by a zombie process makes every start fail fast, not slow. Read the error: port-in-use is a different problem than slow start.
• Internationalized and versioned sites multiply startup cost. Measure on the real config, not a minimal one.
• Waiting on the wrong log line can still race. Wait for the docusaurus ready message specifically, not an intermediate bundler line.
• Memory-constrained sandboxes make cold starts much slower than on a dev machine. Measure in the same environment the agent uses.

Provenance

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