Why does `cypress run --parallel` fail unless you also pass Cypress's `--record`?
answer
- Which half of Cypress is open source
- A flag needs something to act on
- Who decides which machine gets which spec
- Validation happens before the browser launches
- RECORD_PARAMS_WITHOUT_RECORDING
basics
~10 sBecause parallelisation is a Cypress Cloud feature, not a runner feature. The spec-splitting coordinator lives on the server, so Cypress rejects --parallel, --group, --tag, --ci-build-id and --auto-cancel-after-failures up front when --record is absent.
solid answer
~40 sThe Cypress binary can run specs, but it has no way to decide which of your CI machines gets which spec. That coordination happens in Cypress Cloud, so the flags that describe a distributed run — `--parallel`, `--group`, `--tag`, `--ci-build-id` and `--auto-cancel-after-failures` — only mean something once `--record` has created a run record on the server. Pass one without `--record` and Cypress fails validation before launching a browser, with `RECORD_PARAMS_WITHOUT_RECORDING`. There is a mirror guard too: `--ci-build-id` with neither `--group` nor `--parallel` gives `INCORRECT_CI_BUILD_ID_USAGE`. The practical reading is a cost statement rather than a configuration bug — balancing is a paid, hosted capability, and the free alternative is splitting the suite yourself with per-job `cypress run --spec` globs.
go deeper
Recall that cypress run alone is complete and free, and that --parallel is refused without --record. Being able to name the error rather than guessing at a typo is enough at this level.
Explain why the refusal is structural: the spec coordinator lives on the server, so the flag has no local implementation to fall back on. Name the whole rejected set, not just --parallel.
Show that you read the error as an architecture and cost statement. Be ready to say what your pipeline does when the record key is missing or rotated, and whether a Cloud outage should be able to fail a build.
Own the trade explicitly. Argue when a paid coordinator is worth a networked dependency in the build path, and what you keep true so cypress run without any flags stays a valid command.
## Two products wearing one name Cypress ships two things that people talk about as if they were one. The first is the **open-source runner** you install from npm: `cypress run` discovers your specs, launches a browser, executes them and exits with a status your pipeline can read. The second is **Cypress Cloud**, a hosted service the runner can be told to talk to. Everything the runner does on its own — retries, screenshots, videos, reporters, the exit code — costs nothing and needs no network. Deciding *which of your CI machines runs which spec* is not one of those things. That decision needs a coordinator every machine can reach and agree on, and in Cypress that coordinator is the Cloud. So the flags that describe a distributed run are verbs whose object is a **run record** held on the server: - `--parallel` — ask the coordinator to hand this machine one spec at a time. - `--group` — label this machine's contribution inside a larger run. - `--tag` — attach metadata to the run record so you can tell runs apart later. - `--ci-build-id` — the value that tells the coordinator these separate machines are one run. - `--auto-cancel-after-failures` — ask the coordinator to end the run early. `--record` is the flag that creates the run record in the first place. Without it there is no object for those verbs to act on, so Cypress refuses the invocation up front rather than running half of it. ## The exact failure, and its mirror image Pass any of those five without `--record` and the run dies before a browser launches, with the error Cypress calls `RECORD_PARAMS_WITHOUT_RECORDING`. Its text is blunt: *"You passed the `--ci-build-id`, `--group`, `--tag`, `--parallel`, or `--auto-cancel-after-failures` flag without also passing the `--record` flag ... These flags can only be used when recording to Cypress Cloud."* Note that it is a **pre-flight validation**, not a runtime failure — you have not burned a CI minute on a browser when it fires. There is a second, opposite guard that catches the other half of the same misunderstanding: | You passed | You also need | Failure if you do not | |---|---|---| | `--parallel` | `--record` | `RECORD_PARAMS_WITHOUT_RECORDING` | | `--group` | `--record` | `RECORD_PARAMS_WITHOUT_RECORDING` | | `--tag` | `--record` | `RECORD_PARAMS_WITHOUT_RECORDING` | | `--ci-build-id` | `--record`, **plus** `--group` or `--parallel` | `RECORD_PARAMS_WITHOUT_RECORDING`, else `INCORRECT_CI_BUILD_ID_USAGE` | `--ci-build-id` on its own, with recording enabled but neither `--group` nor `--parallel`, is rejected too: it is only meaningful as the thing that stitches several machines together, so supplying it alone signals that you thought it did something it does not. ## What the guard is really telling you Read the error as a statement about **where the feature lives**, and the cost conversation writes itself. Spec balancing, cross-machine grouping and early cancellation are server-side features of a commercial service. They are not held back by a licence check inside the binary you already have — the binary genuinely does not contain them, which is why there is nothing to unlock and no offline flag to find. The vendor's own documentation states that a self-hosted Cypress Cloud is not available, so "run the coordinator ourselves" is not an option on the table either. That leaves exactly two shapes for fanning a Cypress suite out across machines, and an interviewer asking this question usually wants to hear both named: 1. **Record and parallelise.** Add `projectId` and a record key, pass `--record --parallel`, and let the service assign specs. You get balancing and one combined view of the run, and you take on a paid, networked dependency in the middle of your build. 2. **Split the specs yourself.** Give each CI job a different `cypress run --spec` glob and no record key at all. Nothing is metered and nothing phones home, and you now own the partition, its drift, and the job of assembling the results. ## Where teams trip over this In a multi-package storefront monorepo the mistake is usually inherited rather than invented. Someone copies a `--parallel --group checkout` line out of a blog post or another repository's workflow into a job that has no record key, and every CI job fails identically and instantly. 1. Read the error name — `RECORD_PARAMS_WITHOUT_RECORDING` says the cause exactly. 2. Decide which of the two shapes above you actually want, rather than hunting for the missing flag that makes parallelism free. 3. If you want recording, set `projectId` in `cypress.config.js` and supply the key through the environment, not on the command line where it lands in build logs. 4. If you do not, strip **all five** flags, not just `--parallel` — leaving `--tag "nightly"` behind reproduces the same error with a more confusing message.
- What happens if you pass `--ci-build-id` with `--record` but without `--group` or `--parallel`?Cypress rejects it with `INCORRECT_CI_BUILD_ID_USAGE`. The build id exists to tell the service that several separate machine invocations belong to one run, so on its own it has nothing to stitch together. The guard is deliberate: silently accepting it would let a team believe machines were being grouped when each was recording an unrelated run.
- Can you get spec balancing without Cypress Cloud by running your own coordinator?Not as a drop-in. The documentation states no self-hosted Cypress Cloud is available, and the runner has no protocol hook for substituting your own scheduler. Teams that decline the service split the suite themselves — one `cypress run --spec` glob or file-list chunk per CI job — and accept that the partition is static and hand-maintained.
The runner is an engine and the Cloud is the dispatcher. You own the engine outright, but asking four of them to divide one delivery route between them requires the dispatcher, and shouting the instruction at an engine with no radio just stalls it.
saying these in an interview costs you the question
- Says --parallel splits specs locally inside one machine
- Thinks a licence key unlocks parallelism in the binary
- Believes --record only affects reporting, not orchestration
- Claims you can self-host Cypress Cloud to get balancing
- Confuses --ci-build-id with a CI job id that works alone