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 network-specific Cloud errors and exits with code 112 under --posix-exit-codes when Cloud negotiation fails; also makes API timeouts configurable and refactors run/exit handling.

Behavior/CLI:
- Exit with 112 when Cloud negotiation (record/parallel) fails due to network under --posix-exit-codes.
- Refactor startInMode to async with unified exit paths; propagate posixExitCodes; remove modes/exit.ts and inline exit-with-code logic.
Errors/Schema:
- Add CLOUD_CANNOT_PROCEED_IN_PARALLEL_NETWORK and CLOUD_CANNOT_PROCEED_IN_SERIAL_NETWORK with new templates and snapshots.
Cloud API:
- Make default request timeout configurable via CYPRESS_INTERNAL_API_TIMEOUT (used across run/instance/test/artifact calls).
Tests:
- Add integration/system tests covering network failures, POSIX exit codes (1 vs 112), and new error outputs.
Docs/Changelog:
- Update CHANGELOG.md (15.5.0) noting new exit code behavior.

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

…re enabled

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

cypress Run #66299

Run Properties: Failed #66299 • edcf651d0c: Merge branch 'develop' into feat-api-failure-exit-112

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

Test results
Failures	`3`
Flaky	`12`
Pending	`1102`
Skipped	`4`
Passing	`26705`
View all changes introduced in this branch ↗︎

Warning

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

UI Coverage `45.69%`
Untested elements	`184`
Tested elements	`159`

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

Tests for review

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

View Output

Test Artifacts

cy.origin - cookie login > general behavior > handles browser-sent cookies being overridden by server-kept cookies

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

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

View Output

Test Artifacts

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

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

studio/studio.cy.ts • 1 failed test • app-e2e

View Output

Test		Artifacts
Cypress Studio > updates an existing test with assertions		`Test Replay` `Screenshots`

commands/querying/querying.cy.ts • 1 flaky test • 5x-driver-electron

View Output

Test		Artifacts
... > intercept aliases > returns null if no xhr is found		`Test Replay`

issues/28527.cy.ts • 1 flaky test • 5x-driver-electron

View Output

Test		Artifacts
issue 28527 > fails and then retries and verifies about:blank is not displayed		`Test Replay` `Screenshots`

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>

issues/28527.cy.ts • 1 flaky test • 5x-driver-firefox

View Output

Test		Artifacts
issue 28527 > fails and then retries and verifies about:blank is not displayed		`Screenshots`

The first 5 flaky specs are shown, see all 12 specs in Cypress Cloud.

cursor · 2025-10-08T13:16:35Z

packages/server/lib/modes/record.ts

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


Bug: Redundant Throw Causes Runtime Error

The throw throwErr(...) statement is incorrect. Since throwErr already throws an error, the additional throw keyword is redundant and will cause a runtime error.

I have a feeling this is a TS issue?

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

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?

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

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.

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'

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

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

cursor bot reviewed Oct 8, 2025

View reviewed changes

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

		@@ -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

Uh oh!

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!

cursor bot Oct 8, 2025

Choose a reason for hiding this comment

Bug: Redundant Throw Causes Runtime Error

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!

Uh oh!

cacieprins commented Oct 2, 2025 •

edited by cursor bot

Loading

cypress bot commented Oct 2, 2025 •

edited

Loading