Chromatic "Missing project token" in CI

By Kaveh Alemi·Latchkey

The Chromatic CLI authenticates each build with a project token. "Missing project token" means neither the --project-token flag nor the CHROMATIC_PROJECT_TOKEN environment variable was set for the step, usually because the secret was not wired in.

What this error means

The Chromatic step fails immediately with "Missing project token" (or "Invalid project token") before any snapshots are published.

✖ Missing project token
Set CHROMATIC_PROJECT_TOKEN or pass --project-token

Common causes

The secret is not exposed to the step

The token is stored as a repository secret but never mapped into the step's environment, so the CLI sees nothing.

The token is only set for the base branch

Secrets are not passed to workflows triggered by forked pull requests, so the token is absent there.

How to fix it

Wire the project token secret into the step

1. Store the token as a repository or organization secret named CHROMATIC_PROJECT_TOKEN.
2. Map it into the Chromatic step env or pass --project-token.
3. Re-run the workflow.

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

Handle forked pull requests

For forks, run Chromatic on pull_request_target or gate the step so it skips when the secret is absent rather than failing.

- if: ${{ env.CHROMATIC_PROJECT_TOKEN != '' }}
  uses: chromaui/action@latest
  env:
    CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

How to prevent it

• Store the Chromatic token as a secret and map it into the step.
• Account for forked PRs where secrets are not available.
• Never commit the project token into the repository.

Frequently asked questions

Related guides

References

• GitHub Actions documentation