How to fix a Chromatic story that times out

A Chromatic timeout can happen while a single story is being captured, while Storybook is starting or building, or during build verification. Identify the failing stage first: reducing story work can help a capture timeout, while a build verification timeout calls for checking the production build, the relevant CLI timeout, or the connection.

Chromatic documents up to 15 seconds to render a story and an additional 15 seconds to execute interaction tests when present. These capture windows are distinct from the CLI’s waits for Storybook to start or build. Chromatic’s resource loading guidance explains the capture behavior.

1. Identify which stage timed out

Start with the exact error and the surrounding Chromatic log. A story that works in local development can still time out during capture; a whole build can instead fail because Storybook did not start or build in time, verification did not finish, or Chromatic lost its connection to the server.

Symptom	Likely stage	Start here
One story is slow or times out during snapshot capture	Story rendering or interaction test	Inspect the story’s render work, play function, assets, and addons.
Storybook build or startup does not finish	Storybook startup or production build	Reproduce the production build locally and check the matching timeout.
“Build verification timed out”	Build verification	Inspect production build output and logs; consider a prebuilt Storybook or the relevant timeout.
Whole-build timeout that happens intermittently	Server or network connection	Check that the Storybook server stays alive and internet connectivity remains available.
Interactions differ in CI and locally	Environment or interaction test	Compare Node and test/user-event package versions, and reproduce in production mode.

Record the affected story, exact error, whether the failure is repeatable, and whether it happens locally, in CI, or only in Chromatic. This helps distinguish a slow story from an unavailable build or connection.

2. Fix a story capture timeout

Look for work that delays rendering or interaction completion. Chromatic identifies long play-function sequences, especially programmatic delays; large component rerenders; large data files and static assets; and unnecessary addons or assets as potential causes.

Review the story’s render path. Remove calculations, data loading, rerenders, or setup that does not affect the snapshot. If a component repeatedly updates, find the state or effect causing the extra work.
Inspect its play function. Keep interactions needed to establish the visual state. Remove unnecessary steps and avoid arbitrary waits when a deterministic interaction or readiness condition will work.
Reduce asset and data overhead. Trim large fixtures and avoid loading assets the story does not need. Where practical, serve images and other resources locally; external hosts add network variability.
Disable irrelevant addons for Chromatic runs. An addon that is not needed to render or capture the story can add startup or rendering work. Chromatic’s resource loading documentation describes conditionally disabling addons.
Check resource failures. If a resource fails to load, Chromatic retries and may then capture with a warning. Read the capture log for failed or slow resources instead of assuming every warning is a timeout.

After each change, recapture the affected story and confirm that the resulting visual state is still the one the test intends to document. A higher global timeout can hide a slow or stuck story without fixing its cause.

3. Reproduce startup, build, and verification failures

Chromatic’s CLI builds Storybook in production mode. A development server starting successfully does not prove that a production build will succeed or complete within the available time.

Run the same production Storybook build locally that CI or Chromatic uses.
Open the generated Storybook and inspect the affected stories, browser console, and build output.
Use Chromatic diagnostics to capture more detail about the failing build.
If Storybook’s build itself is timing out inside Chromatic, build Storybook in a separate CI step and pass its output directory with --storybook-build-dir.
If the timeout is caused by a large Storybook archive, consider Chromatic’s --zip option as described in its build verification timeout FAQ.

For intermittent failures, check that the server remains alive for the full build and that internet access is stable. Chromatic lists server shutdown and lost internet access as examples of connection loss that can cause a build timeout. Retry after addressing the interruption; repeated retries alone will not repair a reproducible production-build error.

4. Set the timeout that matches the failing stage

Chromatic has separate environment variables for waiting on Storybook startup and Storybook build. The documented defaults below are from its configuration reference; check the current reference when configuring a new project.

Variable	What it controls	Documented default	When to adjust
`CHROMATIC_TIMEOUT`	Wait for `storybook dev`	`300000` ms (5 minutes)	Storybook startup genuinely needs longer.
`STORYBOOK_BUILD_TIMEOUT`	Wait for `storybook build`	`600000` ms (10 minutes)	The production build is slow but succeeds when given more time.

Set only the variable for the stage that is actually failing. For example, in a POSIX shell, to allow a production Storybook build up to 15 minutes for one command:

STORYBOOK_BUILD_TIMEOUT=900000 npx chromatic --project-token=<your-project-token>

For a persistent CI setting, configure the variable in the CI job environment. Keep the value in milliseconds. Use your project’s usual secure mechanism for the Chromatic project token.

Increasing a wait limit can help when startup or build work is simply slow. It will not fix a story that hangs, a broken production build, or resources and servers that cannot be reached.

5. Check interaction-test environment parity

If an interaction test works locally but fails in CI or Chromatic, compare the Node version and the relevant test and user-event package versions across environments. Reproduce the behavior using a production Storybook build. Chromatic’s interaction-test debugging guide recommends checking version differences and production-mode behavior.

6. Troubleshooting common errors

Error or symptom	Possible cause	Fix
Story times out during capture but works locally	Capture-specific render work, slow play-function steps, asset loading, or addon work.	Inspect the story and capture logs; trim unnecessary work and make resources predictable.
“Build verification timed out”	Slow or broken production build, build verification delay, or oversized Storybook archive.	Reproduce the production build, inspect diagnostics, try a prebuilt Storybook with `--storybook-build-dir`, or consider `--zip` and the relevant timeout.
Storybook never becomes ready	Startup is slower than the configured wait or the server exits.	Inspect startup output and server lifetime; adjust `CHROMATIC_TIMEOUT` only if startup is genuinely slow.
Production build fails although development works	A production-mode issue not present in the dev server.	Run the production build locally and fix the first underlying build error.
Capture warning about a failed resource	A resource request failed or was delayed; Chromatic may retry before capturing with a warning.	Use the log to identify the resource, make it available reliably, or remove an unnecessary dependency.
Only CI interaction tests fail	Node or interaction-test package versions differ from local.	Align relevant versions and reproduce against the production build.
Intermittent whole-build timeout	Storybook server stops, or internet connectivity drops.	Keep the server alive and check the CI runner’s connection before retrying.
A longer timeout changes nothing	The process is hung, the build is broken, or a dependency cannot load.	Return to the logs and isolate the failing stage and underlying work.

7. Improve capture speed and reliability

Keep each story’s fixture and asset set limited to what affects its rendered state.
Prefer local resources where practical so capture does not depend on an external host’s availability or response time.
Keep play functions focused on the interaction state being captured; avoid arbitrary delays.
Disable addons that do not contribute to Chromatic rendering or tests.
Use the same production build and relevant runtime and package versions in local reproduction and CI.
Reserve timeout increases for slow work that completes reliably when given more time.

These changes reduce avoidable work and external dependencies. The documented timeout values are limits for their respective startup or build waits, not performance targets for every project.

8. Or skip the browser setup

For a standalone website screenshot, ScreenshotNeo provides a website screenshot API and MCP server. It is for capturing website pages; Chromatic remains the tool in this guide for Storybook visual testing.

One GET request returns an image or PDF. The example below saves a WebP screenshot of Stripe. Create an API key in ScreenshotNeo, then replace YOUR_API_KEY and the target URL. See the ScreenshotNeo API documentation for request options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
with open("shot.webp", "wb") as f:
    f.write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status} ${await res.text()}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots.

9. FAQ

Why can a story pass locally but time out in Chromatic?

Capture runs under different timing and resource conditions. Inspect story work, assets, addons, and the capture log; a local development result does not rule out a capture-specific delay.

Should I increase both timeout variables?

No. They wait for different Storybook stages. Identify whether startup or the production build is slow, then change only that stage’s setting.

Will a longer timeout fix a hanging story?

No. It gives slow work more time, but a hang, broken build, or unavailable resource needs its underlying cause fixed.

Does a capture timeout mean the entire Chromatic build has a 15-second limit?

No. Chromatic documents 15 seconds for story rendering and an additional 15 seconds for interaction tests when present. Those capture windows are not a universal limit for the whole build.