Cypress "Record Key is not valid" - cypress run --record Fails in CI

By Daniel Zoghalchali·Latchkey

Recording a run to Cypress Cloud needs a valid Record Key tied to the project. The run fails when --record is passed without a key, the key is wrong/rotated, or the projectId does not match the key’s project.

What this error means

cypress run --record aborts with "Your Record Key ... is not valid with this projectId" or "You passed the --record flag but did not provide a Record Key." Non-recording runs work; only the Cloud-recording path fails.

Cypress output

You passed the --record flag but did not provide a Record Key.

# or
Your Record Key <...> is not valid with this projectId: abc123
Please log into the Dashboard to verify.

Diagnose it: browser, server, or timing?

End-to-end failures in CI are dominated by three causes that have nothing to do with the test: the browser binary is missing, the application under test is not listening yet, or the test raced the page. Establish which before reading the assertion.

Terminal

# 1. are the browsers actually installed in THIS job?
npx playwright install --with-deps chromium
npx playwright --version

# 2. is the app up before the tests start?
npx wait-on http://localhost:3000 --timeout 60000

# 3. capture evidence for the failure you cannot reproduce
npx playwright test --trace on --video retain-on-failure

Common causes

Record Key missing from the CI environment

The CYPRESS_RECORD_KEY secret is not set in the job (or not exposed to forks), so --record has no key to authenticate with.

Key/projectId mismatch or rotated key

The key belongs to a different project than the configured projectId, or it was rotated in the Cloud dashboard and the CI secret still holds the old value.

How to fix it

Provide the key via a CI secret

Set the record key as an environment secret and reference it - do not hard-code it.

.github/workflows/ci.yml

# .github/workflows/ci.yml
- run: npx cypress run --record
  env:
    CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}

Align the key, projectId, and rotation

Confirm projectId in cypress.config matches the project the key belongs to.
Re-copy the key from the Cloud dashboard if it was rotated, and update the CI secret.
Remember forked-PR builds do not get secrets - skip recording or use a dedicated flow there.

Make the browser cache safe

Key the browser cache to the exact test-runner version. A cache restored from a different version gives you a binary that does not match the client and fails in a way that reads like a missing install.
Install browsers after dependencies, not before; a dependency install can replace the package that owns the browser path.
Prefer the vendor container image when the runner allows it. It removes the whole class of missing-system-library failures.

How to prevent it

Store the record key only as a CI secret.
Keep projectId and the key’s project in sync.
Rotate the CI secret whenever the Cloud key is rotated.

Frequently asked questions

What causes Cypress "Record key is not valid"?

There are 2 common causes: record key missing from the ci environment and key/projectid mismatch or rotated key. The CYPRESS_RECORD_KEY secret is not set in the job (or not exposed to forks), so --record has no key to authenticate with.

How do I fix Cypress "Record key is not valid"?

There are 2 fixes depending on which cause you have: provide the key via a ci secret and align the key, projectid, and rotation. Work through them in order, since the first is the most common.

What does Cypress "Record key is not valid" actually mean?

cypress run --record aborts with "Your Record Key ...

How do I stop Cypress "Record key is not valid" happening again?

Store the record key only as a CI secret. The prevention section lists 3 changes that keep it from recurring.

References

GitHub Actions documentation