Chromatic build is stuck in progress: how to fix it

If a Chromatic build is stuck in progress, first check how long it has been running. Chromatic automatically cancels builds stuck in progress after two hours. If it remains stuck beyond that, Chromatic says to contact support@chromatic.com or use its in-app chat. The documented guidance does not provide a universal root cause or promise an immediate manual cancel option.

1. Check the elapsed time

Open the Chromatic build page and note when the build started. If less than two hours have passed, Chromatic’s published guidance is to allow its automatic cancellation threshold to pass. Avoid repeatedly starting new builds until you know whether the existing CI workflow is still running; duplicate runs can make it harder to identify which build corresponds to which commit.

If more than two hours have passed and the build still says it is in progress, move to escalation below. The two-hour figure is Chromatic’s documented automatic-cancellation interval, not a general timeout for all CI jobs.

2. Compare the Chromatic build with the CI run

Check both status surfaces: the build page in Chromatic and the CI run that invoked Chromatic. Chromatic’s CLI and GitHub Action publish Storybook to Chromatic and initiate tests when those tests are enabled. The CI step logs can show whether the workflow is still executing or has completed while the Chromatic build remains in progress. Storybook’s Chromatic integration documentation describes the CLI and action.

Chromatic status	CI status	What to do
In progress, under two hours	Running	Inspect the active CI step and logs. Wait for the documented two-hour cancellation threshold if it does not resolve.
In progress, under two hours	Completed or failed	Record the CI result and logs. Compare the build URL, commit, and workflow run to confirm they refer to the same attempt.
In progress, over two hours	Any status	Contact Chromatic support or use in-app chat; include the build and CI details.
Not in progress	Running or failed	Investigate the CI workflow state separately. A CI job and a Chromatic build are related but distinct status surfaces.

Do not assume the status alone proves a token failure, code error, or CI provider outage. The consulted documentation does not identify one cause that explains every stuck build. Use the run-specific logs and build details to diagnose the particular case.

3. Review the workflow configuration

Compare the workflow with Storybook’s official publishing example. Verify that the repository is checked out, dependencies are installed, and the Chromatic project token is available to the workflow as a CI secret. Storybook’s example uses full Git history with fetch-depth: 0 and the Chromatic action. These are configuration details to inspect, not guaranteed fixes for every in-progress build.

name: Publish Storybook
on: push
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

This is an illustrative workflow based on the documented setup pattern. Match action and Node versions to your repository and current supported configuration. Keep the project token in the CI secret store; do not paste it into public logs or commit it to the repository. See Storybook’s publishing guide and deployment tutorial.

Confirm the workflow checks out the intended branch and commit.
Confirm dependencies install successfully before the Chromatic step.
Confirm the secret name used in the workflow matches the configured CI secret.
Read the complete Chromatic step output, including any preceding build or upload errors.
Compare the build URL and commit shown by Chromatic with the CI run that launched it.

Chromatic’s integration documentation lists support for current LTS Ubuntu, Windows Server, and macOS versions; Node.js Current, Active, or Maintenance (LTS) releases; and Storybook 6.5 or later. Other combinations may work but are not officially supported, and features can vary by platform and version. Check the current integration page before changing a version-specific setup.

4. Keep Chromatic publishing separate from test-runner status

A separate Storybook test-runner job may be running or failing independently of the Chromatic publishing build. Storybook describes the test runner as a tool that can run locally or in CI and be extended for different tests; Chromatic is a cloud service for visual and component tests integrated with a Git provider. Check which job or status is actually stuck before changing either setup. See the test-runner documentation.

The test-runner page includes a CI recipe that builds Storybook, serves it, waits for port 6006, and runs tests, with a 60-minute timeout in that example job. That example timeout is not Chromatic’s documented automatic-cancellation threshold; Chromatic’s FAQ specifies two hours.

5. Escalate a build that is still stuck after two hours

Chromatic’s FAQ directs users whose build remains stuck beyond two hours to contact support@chromatic.com or use Chromatic’s in-app chat. Include enough run-specific evidence to help support investigate:

The Chromatic build URL and approximate start time.
The CI provider and link to the corresponding workflow run.
The commit or branch associated with the build.
The relevant Chromatic step logs and the final CI status.
Whether the build has passed the two-hour mark.

These details are practical diagnostics to attach; Chromatic’s documented escalation route is support or in-app chat.

Or skip the browser setup

For capturing a page as an image while you investigate a visual issue, ScreenshotNeo offers a website screenshot API and MCP server. A single request returns a PNG, JPEG, WebP, or PDF. This does not cancel or diagnose a Chromatic build; it is an alternative for capturing a page without setting up browser automation. See the 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.webp

import requests

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

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 import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; responses identify the page verdict and billing status.
An MCP server lets AI agents, including Claude and Cursor, take screenshots with take_screenshot, inspect pages with get_page_info, and capture PDFs with capture_pdf.
1,000 screenshots a month are free with no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

Common errors and fixes

Symptom	Likely interpretation	Next step
Chromatic is in progress, but CI says the run finished	The two status surfaces may have diverged, or you may be looking at different attempts.	Match the build URL, commit, and workflow run; save the logs and escalate if the build passes two hours.
The Chromatic action cannot access its project token	The secret may be missing, unavailable to this event, or named differently from the workflow reference.	Check the CI secret configuration and workflow secret name. Keep the token private.
Checkout or dependency installation fails before Chromatic runs	The workflow may not have reached the publishing step.	Fix the failing earlier CI step, then rerun and verify the new run’s build link.
A separate test-runner job is stuck	That job’s status is not necessarily the Chromatic build status.	Inspect the test-runner logs and job timeout separately from the Chromatic build page.
Build remains in progress beyond two hours	It has exceeded Chromatic’s published automatic-cancellation interval.	Contact Chromatic support or use in-app chat with the build URL and CI evidence.

These are checks, not claims that a particular symptom has one universal cause. The available official guidance documents the timeout and escalation path, but does not assign a single root cause to all stuck builds.

Reliability and cost considerations

The published FAQ’s two-hour cancellation behavior gives you a point at which to escalate; it does not identify why an individual run stopped progressing. Preserve the CI run link and logs before rerunning so the original attempt remains diagnosable. Check whether the CI job and Chromatic build are both active before deciding a rerun is needed.

The research sources do not specify a price or billing consequence for a stuck build, so this guide makes no cost claim about Chromatic. If you need an independent page capture for visual reference, ScreenshotNeo’s stated billing rule is that only clean shots are billed; bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing.

FAQ

Can I cancel a Chromatic build manually?

The cited Chromatic FAQ documents automatic cancellation after two hours and directs users with builds still stuck beyond that to support or in-app chat. It does not document a general immediate manual-cancel procedure.

Does a stuck build mean my Storybook code is broken?

Not by itself. Check the CI result, Chromatic build page, and logs; the consulted documentation does not identify one universal cause.

Is the test runner’s 60-minute example the Chromatic timeout?

No. The 60-minute timeout appears in a Storybook test-runner CI example. Chromatic’s FAQ states a two-hour automatic-cancellation interval for builds stuck in progress.