First identify what is timing out: one story during snapshot capture, Storybook while starting or building, build verification, or the connection to the Storybook server. These are different failure stages, so increasing a timeout is useful only when it matches the stage that is actually slow.
Identify where the timeout happens
Use the failing log message and timing to classify the problem before changing configuration.
As an Amazon Associate I earn from qualifying purchases.
- One story times out during capture: Storybook may work locally, but a particular story is slow to render, run interactions, or load resources.
- Storybook startup or build is slow: The failure occurs while Chromatic waits for
storybook devorstorybook build. - Build verification times out: The overall build fails with “Build verification timed out.” Check production-build behavior, the applicable timeout, and whether the Storybook server stayed available.
- Intermittent whole-build failure: Chromatic may have lost its connection to the server or the internet during the build.
Chromatic documents distinct waits for story capture and for Storybook startup/build. A capture timeout is not the same as a whole-build timeout.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Fix a story that is slow during capture
Chromatic’s resource-loading guidance documents 15 seconds to render a story and an additional 15 seconds to execute interaction tests, when present. These are capture-process timings, not a universal deadline for an entire Chromatic build. If resources fail to load, Chromatic retries and can capture with a warning.
#1 Best Overall
- Grafco Ishihara Test Chart Book
- Package Info: Each
- Includes four special plates for tests to determine the kind and degree of defect in color vision.
- Image may not reflect actual product sold. Please read description carefully.
- GHF1254
Reduce work that does not affect the snapshot
- Inspect the story’s play function for long sequences, especially programmatic delays. Remove waits that are not needed to reach the state you want to capture.
- Look for large component rerenders or expensive setup. Simplify the story’s data and work where possible without changing the intended visual state.
- Review large data files and static assets. Keep only the data and assets the story needs.
- Conditionally disable addons that are irrelevant during Chromatic runs, rather than loading unnecessary work for every capture.
Make resource loading predictable
External images and other resources add network variability. Serve assets locally where practical, and verify that the resources required by the story are available to Chromatic. A missing or slow resource may trigger retries and warnings rather than an immediate hard failure, so inspect the capture output as well as the timeout message.
Reproduce Storybook’s production build
Chromatic’s CLI builds Storybook in production mode. A development server that works locally does not rule out a production-build error or a story that behaves differently after building. Follow the CLI guidance to reproduce the production behavior and use Chromatic diagnostics to collect more detail.
Rank #2
- Vanishing design: Only people with good color vision can see the sign. If you are colorblind you won’t see anything.
- Transformation design: Color blind people will see a different sign than people with no color vision handicap.
- Hidden digit design: Only colorblind people are able to spot the sign. If you have perfect color vision, you won’t be able to see it.
- Classification design: This is used to differentiate between red- and green-blind persons. The vanishing design is used on either side of the plate, one side for deutan defects an the other for protans.
- Run the same production Storybook build locally that Chromatic runs.
- Open the built Storybook and check the failing story, browser console, and any failed resource requests.
- Compare local and CI behavior. If interaction tests differ, check Node and relevant test or user-event package versions in both environments, as described in Chromatic’s interaction-test debugging guidance.
- If the build is timing out inside Chromatic, consider building Storybook as a separate CI step and passing the output directory with
--storybook-build-dir.
Adjust only the timeout for the failing stage
Chromatic’s configuration reference lists separate environment variables and defaults:
| Setting | What Chromatic waits for | Documented default |
|---|---|---|
CHROMATIC_TIMEOUT |
storybook dev |
300000 ms (5 minutes) |
STORYBOOK_BUILD_TIMEOUT |
storybook build |
600000 ms (10 minutes) |
These are Chromatic-documented defaults; check the current configuration reference for your CLI version before changing them. Increase the variable that corresponds to the stage that is genuinely taking longer than its wait limit. For a build-verification timeout, Chromatic’s FAQ also suggests compressing a large Storybook with --zip or increasing the relevant timeout.
Rank #3
- Cover may vary
A longer wait can accommodate slow but successful work. It will not fix a story that hangs, a broken production build, or unavailable resources. Prefer reducing unnecessary work or fixing the underlying failure when possible.
Check server and network continuity
Chromatic says a build can time out if it loses its connection to the server—for example, if the server stops mid-build or internet access drops. Check that the process serving Storybook remains alive for the entire Chromatic run and that the CI environment retains network access. If the failure is intermittent, retry after checking those conditions; Chromatic’s Quickstart also recommends checking connection loss.
Troubleshoot by symptom
| Symptom | Likely area to inspect | Practical next step |
|---|---|---|
| A single story is slow, while other stories capture | Play-function delays, rerenders, large data or assets, addons | Reduce story-specific work and disable irrelevant addons for Chromatic runs. |
| Local development works, but Chromatic fails | Production build or local/CI environment differences | Build and open Storybook in production mode; compare Node and relevant interaction-test package versions. |
| Storybook startup exceeds its wait | storybook dev startup and CHROMATIC_TIMEOUT |
Diagnose slow startup first; adjust the corresponding wait only if startup is slow but healthy. |
| Storybook build exceeds its wait | storybook build and STORYBOOK_BUILD_TIMEOUT |
Reproduce the production build locally; consider building separately and using --storybook-build-dir. |
| Large Storybook repeatedly hits verification timeout | Build size or verification wait | Try Chromatic’s documented --zip compression suggestion or adjust the relevant timeout. |
| Failures come and go across whole builds | Server lifetime or internet connectivity | Confirm the server and CI network stay available until the run completes, then retry. |
Or skip the browser setup
If you also need a website screenshot outside the Chromatic workflow, ScreenshotNeo provides a screenshot API and MCP server. It is a separate tool, not a fix for a failing Chromatic build. A single GET request can return an image or PDF; the request below saves a WebP screenshot.
ScreenshotNeo API documentation
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.
Sign up free for 1,000 screenshots a month, with no card required.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
