feat: exit with code 112 when api errors prevent cloud orchestrated runs (record mode, parallel run mode) #32635

cacieprins · 2025-10-02T20:39:32Z

Closes UX/CLI Improvement: Fatal Cy Cloud communication failure exits with a specific exit code #32485

Additional details

Adds 112 as a potential exit code when Cypress is run with POSIX complaint exit codes enabled (--posix-exit-codes). This exit code is used when --record or --parallel mode is unable to communicate with Cypress Cloud API due to network conditions.

Steps to test

How has the user experience changed?

PR Tasks

Have tests been added/updated?
Has a PR for user-facing changes been opened in cypress-documentation? docs: Adds documentation for the 112 exit code when posix-compliant exit codes are enabled. cypress-documentation#6294
[NA] Have API changes been updated in the type definitions?

Note

Adds POSIX exit code 112 when Cloud network errors block recorded/parallel runs, introduces network-specific error types/messages, makes Cloud API timeouts configurable, and updates tests/snapshots accordingly.

Run/Exit Codes (POSIX):
- Exit with code 112 when --posix-exit-codes is enabled and Cloud network errors prevent proceeding in recorded (--record) or parallel (--parallel) runs.
Errors & Schema:
- New errors: CLOUD_CANNOT_PROCEED_IN_PARALLEL_NETWORK and CLOUD_CANNOT_PROCEED_IN_SERIAL_NETWORK with tailored messaging; added to schema.graphql and errors.ts plus snapshots.
Server/CLI:
- Map Cloud network failures to the new error types; revise startInMode/exitErr flow to emit code 112 for these errors; remove modes/exit.ts and inline handling.
- Prefer 64‑bit browsers note left intact; add debug logging and minor refactors.
Cloud API:
- Make request timeouts configurable via CYPRESS_INTERNAL_API_TIMEOUT; use as default across Cloud API calls.
Stability:
- Tweak early-exit handling signature; minor refactors.
Tests:
- Add/adjust integration and system tests (and snapshots) for new errors, exit code 112, configurable timeouts, and messaging; update changelog for 15.5.0.

^{Written by Cursor Bugbot for commit 4152a21. This will update automatically on new commits. Configure here.}

…re enabled

cypress · 2025-10-02T21:13:52Z

cypress Run #66384

Run Properties: Failed #66384 • 4152a21977: Merge branch 'develop' into feat-api-failure-exit-112

Project	`cypress`
Branch Review	`feat-api-failure-exit-112`
Run status	`Failed #66384`
Run duration	`18m 33s`
Commit	`4152a21977: Merge branch 'develop' into feat-api-failure-exit-112`
Committer	`Cacie Prins`
View all properties for this run ↗︎

Test results
Failures	`7`
Flaky	`5`
Pending	`1018`
Skipped	`4`
Passing	`19973`
View all changes introduced in this branch ↗︎

Warning

Partial Report: The results for the Application Quality reports may be incomplete.

UI Coverage `44.99%`
Untested elements	`187`
Tested elements	`157`

Accessibility `97.97%`
Failed rules	`4 critical` `8 serious` `2 moderate` `2 minor`
Failed elements	`101`

Tests for review

commands/waiting.cy.js • 0 failed tests • 5x-driver-electron

View Output

Test		Artifacts

cypress/cy.cy.js • 0 failed tests • 5x-driver-electron

View Output

Test		Artifacts

commands/command_option_immutability.cy.js • 0 failed tests • 5x-driver-electron

View Output

Test		Artifacts

e2e/origin/navigation.cy.ts • 0 failed tests • 5x-driver-electron

View Output

Test		Artifacts

commands/actions/submit.cy.ts • 0 failed tests • 5x-driver-electron

View Output

Test		Artifacts

The first 5 failed specs are shown, see all 623 specs in Cypress Cloud.

e2e/origin/cookie_login.cy.ts • 1 flaky test • 5x-driver-firefox

View Output

Test Artifacts

... > past Max-Age, before Expires -> not logged in

    </td>
  </tr></table>

commands/files.cy.js • 1 flaky test • 5x-driver-firefox

View Output

Test Artifacts

src/cy/commands/files > #readFile > retries to read when ENOENT

    </td>
  </tr></table>

commands/net_stubbing.cy.ts • 1 flaky test • 5x-driver-firefox

View Output

Test Artifacts

... > stops waiting when an xhr request is canceled

    </td>
  </tr></table>

e2e/origin/config_env.cy.ts • 1 flaky test • 5x-driver-firefox

View Output

Test Artifacts

cy.origin- Cypress.config() > serializable > overwrites different values in secondary if one exists in the primary

    </td>
  </tr></table>

e2e/origin/config_env.cy.ts • 1 flaky test • 5x-driver-inject-document-domain-chrome

View Output

Test		Artifacts
cy.origin- Cypress.config() > serializable > overwrites different values in secondary if one exists in the primary		`Test Replay`

AtofStryker · 2025-10-08T15:42:56Z

packages/server/lib/cypress.ts

-  return require('./errors').logException(err)
-  .then(() => {
-    debug('calling exit 1')
+  await require('./errors').logException(err)


any reason we can just import errors at the top of the file since we are starting to move away from CJS?

Because of how the integration tests are set up, this has to be dynamically required for now :(

AtofStryker · 2025-10-08T15:45:15Z

packages/server/lib/cypress.ts

+          break
+        }
+        case 'returnPkg': {
+          const pkg = await require('./modes/pkg')(options)


Can we just import pkg from '@packages/root' at the top of the file since its a bundled package now and just reference it here instead of ./modes/pkg? Would be much simpler

AtofStryker · 2025-10-08T15:45:36Z

packages/server/lib/cypress.ts

+          break
+        }
+        case 'info': {
+          await require('./modes/info')(options)


can we just hoist this import or await import it? If not I'll likely get to this in the launcher refactor

AtofStryker · 2025-10-08T15:47:42Z

system-tests/test/record_spec.js

        })
      })

+      it('errors and exits with 1 when posix exit codes are enabled', function () {


whats the reason the posix tests are added here and not in the posix PR? Is there some type of integration between these two I am missing?

oh I see its the differences between 112 vs 1 exit code

AtofStryker · 2025-10-08T15:49:51Z

packages/errors/test/__snapshots__/CLOUD_CANNOT_PROCEED_IN_PARALLEL_NETWORK.ansi

@@ -0,0 +1,8 @@
+[31mWe encountered an unexpected error communicating with our servers.[39m


this is so much easier to diff now

It really really is!

jennifer-shehane · 2025-10-08T20:21:47Z

cli/CHANGELOG.md

+
+**Features:**
+
+- When the `run` command requires successful negotiation with the Cypress Cloud API and the `--posix-exit-codes` flag is set, Cypress will now exit with code `112` when it cannot determine which spec to run next due to network conditions. These Cloud API negotiations are required when either `--record` or `--parallel` flags are set. Addresses [#32485](https://github.com/cypress-io/cypress/issues/32485). Addressed in [#32635](https://github.com/cypress-io/cypress/pull/32635).


Suggested change

- When the `run` command requires successful negotiation with the Cypress Cloud API and the `--posix-exit-codes` flag is set, Cypress will now exit with code `112` when it cannot determine which spec to run next due to network conditions. These Cloud API negotiations are required when either `--record` or `--parallel` flags are set. Addresses [#32485](https://github.com/cypress-io/cypress/issues/32485). Addressed in [#32635](https://github.com/cypress-io/cypress/pull/32635).

- When `cypress run` is run with the `--record` or `--parallel` flags and the `--posix-exit-codes` flag is set, Cypress will now exit with code `112` when it cannot determine which spec to run next due to network conditions. Addresses [#32485](https://github.com/cypress-io/cypress/issues/32485). Addressed in [#32635](https://github.com/cypress-io/cypress/pull/32635).

In the CLI docs https://docs.cypress.io/app/references/command-line, these are called "options" rather than "flags"

record, or record AND parallel are valid choices, parallel on its own is an error condition - see https://docs.cypress.io/app/references/error-messages#The---ci-build-id---group---tag---parallel-or---auto-cancel-after-failures-flags-can-only-be-used-when-recording so you don't even need to mention it.

Suggest:
When cypress run is used with the --record option together with the --posix-exit-codes option ...

jennifer-shehane · 2025-10-08T20:29:03Z

packages/server/lib/cypress.ts

+    }
+  }
+
+  debug('calling exit 1')


Can remove I believe

jennifer-shehane · 2025-10-08T20:35:09Z

packages/server/lib/cypress.ts

    }
+    debug('end of startInMode, exit 0')
+
+    return exit(0)


Is it possible to have an 'exitErr'? We used to have handling of this here. I'm not sure when this would happen.

The exitErr is in the catch block above - this would get hit when one of the switch cases that doesn't return is hit (e.g., info).

Before, every switch case returned a promise, even if they didn't need to (this is an old-style way of preventing the Zalgo effect that is rendered obsolete with async/await).

jennifer-shehane · 2025-10-08T20:43:49Z

packages/server/lib/modes/record.ts

+import { getError, AllCypressErrorNames } from '@packages/errors'
+


Suggested change

import { getError, AllCypressErrorNames } from '@packages/errors'

import { getError } from '@packages/errors'

import type { AllCypressErrorNames } from '@packages/errors'

Addressed in 660ab1b

jennifer-shehane · 2025-10-08T20:45:43Z

packages/server/lib/modes/record.ts

            })
          default:
-            return throwErr('CLOUD_UNKNOWN_INVALID_REQUEST', {
+            throw throwErr('CLOUD_UNKNOWN_INVALID_REQUEST', {


I'm not understanding why this would change to throw either.

jennifer-shehane · 2025-10-09T14:20:39Z

packages/server/test/integration/cypress_spec.js

+      })
+    })
+
+    it('exits with code 1 for parallel cloud API failures when posix-exit-codes is enabled', function () {


This title is incorrect

title was correct, assertion was wrong ;) addressed in 3f096f2

cacieprins added 2 commits October 2, 2025 16:37

feat: exit with code 112 on fatal api errors when posix error codes a…

5ac2316

…re enabled

rm dead code

17c1002

cacieprins and others added 3 commits October 3, 2025 10:07

ts

79be6fe

system tests for 112 exit code

d401df8

Merge branch 'develop' into feat-api-failure-exit-112

d61e91d

jennifer-shehane assigned cacieprins Oct 3, 2025

cacieprins and others added 10 commits October 3, 2025 13:16

Merge branch 'develop' into feat-api-failure-exit-112

9affeaa

fix race condition w/ exit codes

3e891c9

only 112 on network errors, not http errors

2d5528b

have connection timeouts run a little bit faster in system tests

25724e9

Merge branch 'develop' into feat-api-failure-exit-112

c321884

new schema for network errors

12a8a1e

112 should only be on network errors, update integration test

e903179

changelog

b405587

Merge branch 'develop' into feat-api-failure-exit-112

afed8c5

changelog

eb8b28b

cacieprins marked this pull request as ready for review October 7, 2025 20:23

cacieprins marked this pull request as draft October 7, 2025 20:23

This comment was marked as outdated.

Sign in to view

cacieprins mentioned this pull request Oct 7, 2025

docs: Adds documentation for the 112 exit code when posix-compliant exit codes are enabled. cypress-io/cypress-documentation#6294

Open

cacieprins and others added 2 commits October 8, 2025 09:09

coerce boolean

ba640a1

Merge branch 'develop' into feat-api-failure-exit-112

edcf651

cacieprins marked this pull request as ready for review October 8, 2025 13:15

This comment was marked as outdated.

Sign in to view

cacieprins requested a review from AtofStryker October 8, 2025 13:52

AtofStryker reviewed Oct 8, 2025

View reviewed changes

jennifer-shehane self-requested a review October 8, 2025 20:22

jennifer-shehane requested changes Oct 9, 2025

View reviewed changes

code review

3f096f2

cacieprins and others added 3 commits October 10, 2025 14:28

review

660ab1b

rm extra debug

7c11f77

Merge branch 'develop' into feat-api-failure-exit-112

4152a21

cacieprins requested a review from jennifer-shehane October 10, 2025 18:31

		@@ -0,0 +1,8 @@
		[31mWe encountered an unexpected error communicating with our servers.[39m


		Features:

		- When the `run` command requires successful negotiation with the Cypress Cloud API and the `--posix-exit-codes` flag is set, Cypress will now exit with code `112` when it cannot determine which spec to run next due to network conditions. These Cloud API negotiations are required when either `--record` or `--parallel` flags are set. Addresses [#32485](https://github.com/cypress-io/cypress/issues/32485). Addressed in [#32635](https://github.com/cypress-io/cypress/pull/32635).

		import { getError, AllCypressErrorNames } from '@packages/errors'

	import { getError, AllCypressErrorNames } from '@packages/errors'
	import { getError } from '@packages/errors'
	import type { AllCypressErrorNames } from '@packages/errors'

feat: exit with code 112 when api errors prevent cloud orchestrated runs (record mode, parallel run mode) #32635

Are you sure you want to change the base?

feat: exit with code 112 when api errors prevent cloud orchestrated runs (record mode, parallel run mode) #32635

Conversation

cacieprins commented Oct 2, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Additional details

Steps to test

How has the user experience changed?

PR Tasks

Uh oh!

cypress bot commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Tests for review

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cacieprins commented Oct 2, 2025 •

edited by cursor bot

Loading

cypress bot commented Oct 2, 2025 •

edited

Loading