Chromatic CLI

This isn’t a Chromatic CLI issue. Check if your machine is using special security or network settings before running the CLI.

By default, DNS resolution is handled by the environment system. If you are experiencing DNS issues (i.e., ENOTFOUND), the CLI will try to switch from the operating system DNS lookup (i.e., dns.lookup) to network DNS resolve (i.e., dns.resolve). If this also fails, the CLI will add CHROMATIC_DNS_FAILOVER_SERVERS to the list of available DNS servers and try again. For additional information regarding Node’s DNS implementation, please refer to their documentation.

If you’ve configured the Chromatic CLI to run with one of the Git environment variables (i.e., CHROMATIC_SHA, CHROMATIC_BRANCH, CHROMATIC_SLUG), you must configure all three. Otherwise, Chromatic will ignore them when running the build.

• --no-interactive: When running the CLI locally, use this flag to get logs like you would in CI, which are more elaborate than the interactive logs. This is automatically enabled in CI, so adding it to a CI script is useless.
• --diagnostics-file: Before terminating the process, this dumps process context information to chromatic-diagnostics.json. This is the first place to look if you see things you didn’t expect. In a CI system, you’ll have to configure this file as a build artifact so you can download it. How to do this depends on your CI provider.
• --dry-run: Use this if you want to debug the CLI without actually publishing your Storybook or running a Chromatic build. Typically, you’d pair this with --diagnostics-file.
• --debug: This enables verbose logging and --no-interactive. Use this if you want to see the nitty-gritty details. Primarily useful if you have issues publishing (uploading) your Storybook to Chromatic.
• --trace-changed: Specifically for TurboSnap, you can use this flag to get a printed tree view of the dependencies between changed files (according to Git) and your story files.
• --only-story-names: If you have specific stories causing problems, you can use this flag to run a build for just those stories (one or more). If you don’t know which stories are available, you can use --list to print a list of all stories in your Storybook, though it will require running a Chromatic build.

Chromatic can’t reach the git repository linked to your project. This usually means one of three things:

• The repository connection has lapsed. Check whether your organization’s permissions for the Chromatic app have changed.
• The repository was renamed or deleted, so Chromatic can no longer find it at the path it has on file.
• Your git access token is no longer valid. Log out of Chromatic and log back in to refresh it.

Also, confirm that git is initialized in the directory you’re running the CLI from (git status).

This is a problem with your Storybook build, not with Chromatic. Chromatic builds your Storybook in production mode, so a package that works in development mode but breaks in a production build will fail here, while running fine locally with storybook dev.

Reproduce it locally the same way Chromatic does:

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

If that fails, fix the build error and re-run. If it succeeds, run Chromatic with diagnostics to capture more detail:

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

Your Storybook contains a runtime error. The full message may look like this:

✖ Failed to extract stories from your Storybook
This is usually a problem with your published Storybook, not with Chromatic.

Build and open your Storybook locally and check the browser console for errors.
Visit your published Storybook at https://<subdomain>.chromatic.com
The following error was encountered while running your Storybook:

Error: page.evaluate: ReferenceError: Cannot access 'it' before initialization

The message doesn’t say which story is responsible, and because stories load on demand, opening your published Storybook may not surface the error in the console at all.

To find the offending story:

1. Open your published Storybook’s iframe.html (the URL is in the CLI output, with /iframe.html appended).

2. In the browser console, run:

   await (window.__STORYBOOK_PREVIEW__?.extract?.() ?? __STORYBOOK_PREVIEW__.extract());

3. The console output names the story that threw.

Fix the runtime error in that story, then rerun your build.

The CLI couldn’t find a build-storybook script in your package.json:

✖ Build script not found
The CLI didn't find a script called "build-storybook" in your package.json.

Add it:

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

If your build script has a different name, point the CLI at it with buildScriptName instead of renaming it.

Chromatic detected that the build output isn’t a valid Storybook and stopped before uploading, so there’s no additional logging to inspect.

Build your Storybook locally to confirm it produces valid output. If it does, build it as a separate step in CI and hand the output directory to Chromatic rather than letting Chromatic build it:

npm run build-storybook
npx chromatic --storybook-build-dir=storybook-static

This usually indicates a TLS problem. Proxies that intercept HTTPS traffic and present their own certificate can break the CLI’s connection to Chromatic.

If the CLI worked previously but has started failing without any changes on your side, your network, DNS, or firewall configuration likely changed.

Check whether your machine can reach index.chromatic.com with a valid TLS certificate. If your organization uses a corporate certificate, your security team will need to allow the connection.

See also local certificate errors.

The project token being passed doesn’t match any Chromatic project. Almost always a configuration problem rather than an outage:

• Confirm the token against the one on your project’s Manage page.
• If the token comes from an environment variable or a secrets manager, confirm the value arriving at the CLI is the raw token and hasn’t been wrapped, encrypted, or truncated in transit.
• If the token was reset, update every place it’s configured.

Error: Unknown argument: /tmp/chromatic--1234-e5X6a7M8p9L0e

The Angular CLI rejects the temporary output directory that Chromatic passes when it builds your Storybook for you. Build Storybook as its own step and pass the result to Chromatic instead:

{
  "scripts": {
    "build-storybook": "ng run components:build-storybook",
    "chromatic": "npm run build-storybook && npx chromatic --storybook-build-dir=static-storybook"
  }
}

This is a warning from your bundler about your Storybook’s output size, not a Chromatic error. It often appears alongside a failing or slow build.

Options, roughly in order of effort:

• Use dynamic import() to split large modules so they load on demand.

• Configure chunking explicitly — build.rollupOptions.output.manualChunks for Vite, optimization.splitChunks for webpack.

• Raise the warning threshold if the size is expected. In Vite:

  vite.config.js

  export default {
    build: {
      chunkSizeWarningLimit: 1000, // KB
    },
  };

  This changes only the warning threshold, not the chunk sizes.

If your build is also timing out, see CHROMATIC_TIMEOUT and STORYBOOK_BUILD_TIMEOUT, and consider passing a prebuilt Storybook with --storybook-build-dir.

Chromatic reuses unchanged files from your previous build instead of re-uploading them. This error means one or more of those files failed to copy.

Re-run the build. If it keeps failing, disable file reuse for that build:

npx chromatic --no-file-hashing

and contact support so we can look into it.

A NoSuchKey 404 for .chromatic/files-copied.txt in verbose output is expected and harmless. Chromatic polls for that file while reusing unchanged files from your previous build, so it’s absent until the copy finishes. It doesn’t affect your build.

Unhandled promise rejection: Invalid version: "x"

This comes from npm, not Chromatic. The version field in your package.json must be parseable by node-semver — that is, it must follow semantic versioning. A leading = or v is stripped, but any other scheme fails.

Update the version to a valid semver string.

For example:

ReferenceError: React is not defined
ReferenceError: _jsx is not defined
ReferenceError: IDBIndex is not defined

A dependency isn’t declared, isn’t installed, or is declared incorrectly, so it’s missing from the production build Chromatic renders.

1. Confirm your Storybook builds and serves locally:

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

2. Run Storybook’s health check to catch mismatched @storybook/* versions:

   npx storybook@latest doctor

3. Check that the missing dependency is declared in package.json and that its configuration (for example, your Vite or webpack config) is complete.