Chromatic "Missing project token" (CHROMATIC_PROJECT_TOKEN) in CI

By Kaveh Alemi·Latchkey

The Chromatic CLI needs a project token to associate the uploaded Storybook build with your project. Without --project-token or CHROMATIC_PROJECT_TOKEN, it cannot start and reports a missing token.

What this error means

The chromatic step fails early with "Missing project token" or "Failed to authenticate." No build is uploaded and no snapshots are captured.

x Missing project token
  Sign in to https://www.chromatic.com/ to get your project token,
  then set CHROMATIC_PROJECT_TOKEN or pass --project-token.

Common causes

The token is not set in the job

The project token secret is not mapped into the step environment, so the CLI has nothing to authenticate with.

The secret is missing on forked PRs

Fork-triggered runs do not receive secrets, so Chromatic has no token on those events.

How to fix it

Provide the project token

Set CHROMATIC_PROJECT_TOKEN from a secret, or pass --project-token.

- run: npx chromatic --project-token=${{ secrets.CHROMATIC_PROJECT_TOKEN }}

Use the official action

The Chromatic GitHub Action reads the token from an input or secret and handles the upload.

- uses: chromaui/action@latest
  with:
    projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

How to prevent it

• Store the Chromatic project token as a secret.
• Pass it via --project-token or CHROMATIC_PROJECT_TOKEN in every run.
• Account for forked PRs where secrets are unavailable.

Frequently asked questions

Related guides

References

• GitHub Actions documentation