Chromatic CI Build Failed With a Missing Storybook Error

If Chromatic CI says Storybook is missing, first identify the exact CLI message, then run the same production Storybook build locally. “Missing Storybook” can mean the CLI cannot find its build script, the build fails, the output directory is invalid, or a dependency is absent in the production build. Those causes need different fixes.

Chromatic’s CLI documentation puts a failed Storybook build plainly: “This is a problem with your Storybook build, not with Chromatic.” Start by diagnosing the build and its inputs before changing Chromatic settings. See the Chromatic CLI troubleshooting guide and configuration reference.

1. Read the exact error and exit category

Do not treat every CI failure as a missing package or missing script. Record the complete error line and nearby output. Chromatic distinguishes cases such as a missing build script, a Storybook build failure, Storybook failing to start, a broken Storybook, and a missing dependency.

Observed message or category	What it points to	First check
“Build script not found”	The CLI cannot find the package script it expects.	Check the scripts in `package.json` and the configured script name.
“Failed to build Storybook”	The production Storybook build itself failed.	Run that production build locally and resolve its first error.
Missing or undefined dependency while rendering	A package may be undeclared, absent from the install, or omitted/misconfigured in the production bundle.	Check dependency declarations, installation and bundler configuration.
Invalid or broken Storybook build	The directory being uploaded may not contain valid built Storybook output.	Serve the generated directory locally and confirm stories load.

2. Reproduce the production build locally

Chromatic’s visual testing workflow uses a production build. A Storybook that works in development mode can still fail when bundled for production.

Install dependencies with the repository’s normal package manager and lockfile.
Run the same build script or custom command used by CI.
Serve the generated directory and open it in a browser; check that the manager loads and stories render.

npm run build-storybook
npx http-server storybook-static -o

These are Chromatic’s standard example commands. Use your project’s actual script and output directory if they differ. A local failure is useful evidence: fix the Storybook build before debugging Chromatic upload configuration.

3. Fix a missing build script

By default, Chromatic looks for a build-storybook package script. A typical script uses Storybook’s build command:

{
  "scripts": {
    "build-storybook": "storybook build"
  }
}

Then run Chromatic from the package that owns this script, for example:

npx chromatic --project-token=<TOKEN>

Replace <TOKEN> with the project token configured for your repository. If your script has another name, tell the CLI which script to run:

npx chromatic --project-token=<TOKEN> --build-script-name=build:storybook

Use buildScriptName in configuration when you want to set the script name there. A script-name setting is for an existing package script; it is distinct from supplying a custom command.

4. Use a custom build command or prebuilt output

If CI builds Storybook with a command that is not a package script, configure a custom build command and its output directory. For example, adapt the command and directory to your project:

npx chromatic --project-token=<TOKEN> \
  --build-command="npm run docs:storybook" \
  --storybook-build-dir=storybook-static

The corresponding configuration options are buildCommand and storybookBuildDir. They solve different needs:

Setting	Use it when
`buildScriptName`	The build is an existing package script, but its name is not the default.
`buildCommand`	Chromatic needs to run a custom build command.
`storybookBuildDir`	The Storybook has already been built, or you need to specify where valid output lives.

When a separate CI step already produces Storybook, make sure it completes before Chromatic runs and that the directory passed to Chromatic is the actual build output. A path that exists but contains unrelated files or incomplete output is not a valid Storybook build.

5. Check missing dependencies and project consistency

If the build reports an undefined reference or a package missing while rendering, check that the package is declared in the appropriate project dependencies, installed in CI, and available to the production bundler. Review the first build error and the relevant Storybook or bundler configuration; later errors can be consequences of the first failure.

For Storybook 7.6 and later, Chromatic’s quickstart recommends running Storybook Doctor as a diagnostic aid. It can identify project consistency issues such as mismatched Storybook versions, duplicated dependencies and incompatible addons:

npx storybook@latest doctor

A Doctor finding is a lead to investigate, not proof that a version conflict caused this specific CI failure.

6. Run Chromatic with diagnostics

If the production build works, the output is valid, and the script or directory is configured correctly, collect more detail from the CLI:

npx chromatic --project-token=<TOKEN> --dry-run --debug --diagnostics-file

Keep the CI log and generated diagnostics file with the reproduction details. The configuration reference also documents a Storybook log-file option, which can help retain build output. Remove or redact secrets such as project tokens, authorization headers and private environment values before sharing logs.

7. Troubleshooting checklist

“Build script not found”

Cause: The expected build-storybook script is absent, or Chromatic runs from a directory whose package manifest does not define it.
Fix: Add the script or set buildScriptName/--build-script-name to the actual script. For a non-script command, use buildCommand and identify its output directory.

“Failed to build Storybook”

Cause: A production build error in Storybook, an addon, a story, a dependency or bundler configuration.
Fix: Run the production build locally, fix the first reported build error, then rerun Chromatic.

Development Storybook works, CI build fails

Cause: Development and production builds differ; production bundling may expose unresolved imports, environment assumptions or configuration gaps.
Fix: Reproduce the production build with the same package manager, lockfile and relevant environment configuration as CI.

Build succeeds but Chromatic says Storybook is broken or missing

Cause: Chromatic may be pointed at the wrong directory, or the directory may not contain the generated Storybook output.
Fix: Serve the output directory locally, verify stories load, then set storybookBuildDir/--storybook-build-dir to that directory.

Package works locally but is undefined in CI

Cause: The dependency may not be declared, may not be installed from the committed lockfile, or may be excluded by bundler configuration.
Fix: Verify the dependency declaration and CI install step; inspect the production bundle configuration and run Storybook Doctor for consistency issues.

Custom script runs but the expected output is absent

Cause: The custom command writes to a different directory, or Chromatic runs before the build step completes.
Fix: Align the command, step order and storybookBuildDir with the actual generated output path.

The cause remains unclear

Cause: The summary line lacks enough detail to distinguish build, startup, dependency and output-directory failures.
Fix: Rerun with --debug --diagnostics-file, retain full logs, and compare the local production build with the CI command and configuration.

8. CI reliability and time cost

Make the CI build reproducible: commit the lockfile, use the repository’s intended package manager, and make the build command and output directory explicit when defaults do not match the project. Ensure the build step finishes before Chromatic consumes prebuilt output. These checks narrow failures to a specific stage and avoid repeatedly changing unrelated settings.

For performance, first identify whether time is spent installing dependencies, building Storybook or uploading it. This troubleshooting path does not establish a universal build-time benchmark. Avoid adding a second build if CI already has a valid output directory; pass that directory instead. Keep diagnostics from failed runs so a later recurrence can be compared with the known-good command and path.

For cost, the cited Chromatic troubleshooting guidance does not provide pricing or a cost estimate for this failure. Resolve the build issue using the existing workflow before adding tools or CI steps solely on speculation.

9. Or skip the browser setup

For screenshot checks of a rendered page while investigating a visual issue, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It does not repair a missing Storybook build or replace Chromatic’s visual testing workflow; it can capture a page with one request after you have a reachable URL.

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}`);

ScreenshotNeo removes cookie banners, newsletter popups and chat widgets before capture. Bot checks, blank pages and failed loads are never billed. Its MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Does “missing Storybook” always mean a missing dependency?

No. It can refer to a missing script, failed production build, invalid output directory or runtime dependency. Use the exact CLI message to choose the branch.

Why does Storybook work in development but fail in Chromatic CI?

Chromatic builds Storybook in production mode for its visual testing workflow. Reproduce that production build locally because it can expose issues hidden in development.

Should I change Chromatic settings before fixing the local build?

Only when the message points to a script or output configuration mismatch. If the production build itself fails locally, fix that build first.

What evidence should I include when asking for help?

Include the complete error, the production build command and result, the configured build script or directory, and the debug diagnostics file. Redact tokens and other secrets.