Error: Unexpected state in testStepFinishedHandler: `step-started` & `step-finished`. Because this error occurred during a `after each` hook we are skipping the remaining tests in the current suite

[vishnula-risk]

Current behavior

When trying to use @badeball/cypress-cucumber-preprocessor alongside other Cypress plugins that register event handlers, the event handlers appear to conflict, resulting in only the last registered handler being executed. Despite following the event-handlers documentation and attempting the recommended workarounds (including cypress-on-fix), the issue still persists.

• I have followed the workarounds documented in the event handlers guide, the solutions provided in cypress-allure-adapter issue #44, and the approach suggested in Cypress issue #5240, but the event handler conflicts still persist.

Browser: Electron 130 (Headless)

Other relevant plugins and versions:

• @cypress/webpack-preprocessor: 6.0.4
• webpack: 5.101.0
• typescript: ^5.5.4
• cypress-file-upload: ^5.0.8
• cypress-io/github-action: v6

Desired behavior

When running Cypress tests with @badeball/cypress-cucumber-preprocessor in our GitHub Actions CI/CD pipeline, all registered event handlers should execute without conflicts, ensuring that HTML reports are successfully generated at cypress/report/report.html and screenshots are captured at src/cypress/cypress/report/screenshots for artifact upload. The cypress-on-fix workaround should allow multiple plugins to coexist properly, preventing event handler overwrites that currently cause missing reports and artifacts in our automated test runs.

Cypress version

14.5.4

Preprocessor version

22.2.0

Node version

20.19.4

Operating system

Ubuntu Latest (GitHub Actions runner) / Linux (self-hosted runner)

Checklist

• I've read the FAQ.
• I've read instructions for logging issues.
• I'm not using cypress-cucumber-preprocessor@4.3.1 (package name has changed and it is no longer the most recent version, see #689).

[badeball]

Despite following the event-handlers documentation and attempting the recommended workarounds (including cypress-on-fix), the issue still persists.

Show me what you’ve actually tried, preferably with a reproducible example.

[vishnula-risk]

Stack Trace:

Error: Unexpected state in afterSpecHandler: step-finished (this might be a bug, please report at https://github.com/badeball/cypress-cucumber-preprocessor)
    at createError (/home/runner/work/web-e2e-automation/web-e2e-automation/node_modules/@badeball/cypress-cucumber-preprocessor/dist/helpers/error.js:10:12)
    at afterSpecHandler (/home/runner/work/web-e2e-automation/web-e2e-automation/node_modules/@badeball/cypress-cucumber-preprocessor/dist/plugin-event-handlers.js:353:43)
    at processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async Object.handler (/home/runner/work/web-e2e-automation/web-e2e-automation/cypress/support/plugins/index.ts:2:1298)

Steps to Reproduce

• Set up Cypress project with @badeball/cypress-cucumber-preprocessor.
• Register event handlers for the same event (e.g., "after:spec") in both plugins using the documented method, including cypress-on-fix.
• Run Cypress tests with cypress run --config-file config/cypress.config.ts --env tags="@tag" or similar commands.
• Observe that only one handler (usually the last registered) is executed, and the expected behavior from the other plugin is missing.

Workaround 1:

Version: "cypress-on-fix": "1.1.0",

My Docs:

cypress.config.ts.txt
package.json.txt

[badeball]

The referenced cypress.config.ts doesn't seem to contain any other plugins. What's its relevance? In any case, you need to read the contributing guidelines again and provide a proper reproducible example. This should almost always be a cloneable repository that I can try out myself.

[vishnula-risk]

debug-logs-masked.txt

Environment:

• Cypress: 14.5.4
• Browser: Electron 130 (headless)
• Node Version: v22.4.0
• OS: Windows

Configuration:

{
  "stepDefinitions": ["cypress/support/step_definitions/**/*.ts"],
  "html": { "enabled": true, "output": "cypress/report/report.html" },
  "filterSpecs": true,
  "omitFiltered": true,
  "isTrackingState": true,
  "attachments": { "addScreenshots": true }
}

Key Timeline (showing the timeout issue):

2025-08-26T07:51:01.583Z cypress-cucumber-preprocessor testStepStartedHandler()
[Test execution runs for ~1 minute 6 seconds]
2025-08-26T07:52:47.719Z cypress-cucumber-preprocessor testStepFinishedHandler()
2025-08-26T07:53:47.932Z cypress-cucumber-preprocessor afterScreenshotHandler()
[Another screenshot after 1 minute]
2025-08-26T07:54:48.092Z cypress-cucumber-preprocessor afterScreenshotHandler()

Step Definitions Loaded: 29 files (including helpers)

Error Sequence:

1. First Error (during test):

   CypressError: `cy.task('cypress-cucumber-preprocessor:test-step-started')` timed out after waiting `60000ms`.
   

2. Second Error (in after each hook):

   CypressError: `cy.task('cypress-cucumber-preprocessor:test-step-finished')` timed out after waiting `60000ms`.
   

3. Final Error (in afterSpecHandler):

   Error: Unexpected state in afterSpecHandler: step-finished 
   (this might be a bug, please report at https://github.com/badeball/cypress-cucumber-preprocessor)
   

Key Observations:

• Gap between testStepStartedHandler() and testStepFinishedHandler() is ~66 seconds
• Multiple afterScreenshotHandler() calls (screenshot attachments enabled)
• Both step-started and step-finished tasks timeout at exactly 60 seconds
• State machine ends up in unexpected "step-finished" state in afterSpecHandler()

Reproduction Steps:

1. Configure preprocessor with attachments: { addScreenshots: true }
2. Run a feature with tag filtering
3. Have a test step that runs longer than 60 seconds
4. Screenshots are captured during the test
5. Both task timeouts occur, leading to the state management bug

[badeball]

If you can't provide a reproducible example, I'm going to close this.

Edit: You're first point indicates a problem with combining plugins and you're last post makes no reference to it. A reproducible example is something unambiguous, which is what I want here.

[vishnula-risk]

@badeball

I'm unable to share detailed logs or code as both the repository and the application are private.

We encountered a plugin-related issue while executing a Cucumber test suite in the CI/CD pipeline. The suite contains 44 scenarios under a specific tag. During execution, a delay in loading the dashboard page after login causes a test to fail with a timeout error. Following this, a plugin error is triggered in the AfterEach hook, which results in the remaining tests being skipped.

I'm running the following feature:

Feature: Dashboard Access

Background:
    Given User is logged in to the page
    And User is on the dashboard page

After the login step, the dashboard page continues to load and fails to render within the 2-minute timeout window. The page hangs, and instead of a standard timeout error, a plugin error is thrown.

Sample log:

2025-09-01T06:24:46.375Z cypress-cucumber-preprocessor testStepFinishedHandler()
2025-09-01T06:25:46.641Z cypress-cucumber-preprocessor afterScreenshotHandler()
    1) Test-ID: Create a report
2025-09-01T06:26:47.057Z cypress-cucumber-preprocessor afterScreenshotHandler()
    2) "after each" hook for "Test-ID: Create a report"

Stack Trace:

CypressError: `cy.task('cypress-cucumber-preprocessor:test-step-started')` timed out after waiting `60000ms`.
CypressError: `cy.task('cypress-cucumber-preprocessor:test-step-finished')` timed out after waiting `60000ms`.
Error: Unexpected state in afterSpecHandler: step-finished (this might be a bug, please report at https://github.com/badeball/cypress-cucumber-preprocessor)

[badeball]

I'm unable to share detailed logs or code as both the repository and the application are private.

You still haven't understood what a reproducible example is. Here's from the contributing guidelines:

But don't panic, no one's after your company secrets. In fact, no one wants to look at your production code at all. A minimal, reproducible example should be completely void of anything resembling company secrets.

Unless you can provide me that, I'm closing this issue.

[czhang0405]

Hi @badeball, this issue also happens occasionally in our Jenkins CI/CD pipeline, too.

Most of time, everything works fine. But sometimes we run failed and got error message:

An error was thrown in your plugins file while executing the handler for the after:spec event.
The error we received was:
Error: Unexpected state in afterSpecHandler: has-reloaded (this might be a bug, please report at <a href="https://github.com/badeball/cypress-cucumber-preprocessor)">https://github.com/badeball/cypress-cucumber-preprocessor)</a>
    at createError (/home/jenkins/.../node_modules/@badeball/cypress-cucumber-preprocessor/dist/helpers/error.js:10:12)
    at afterSpecHandler (/home/jenkins/.../node_modules/@badeball/cypress-cucumber-preprocessor/dist/plugin-event-handlers.js:343:43)
    at processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async /home/jenkins/.../cypress/plugins/index.ts:2:1865
    at async Object.handler (/home/jenkins/.../node_modules/cypress-on-fix/index.js:32:20)

or this one:

An error was thrown in your plugins file while executing the handler for the after:spec event.
The error we received was:
Error: Unexpected state in afterSpecHandler: step-started (this might be a bug, please report at <a href="https://github.com/badeball/cypress-cucumber-preprocessor)">https://github.com/badeball/cypress-cucumber-preprocessor)</a>
    at createError (/home/jenkins/.../node_modules/@badeball/cypress-cucumber-preprocessor/dist/helpers/error.js:10:12)
    at afterSpecHandler (/home/jenkins/.../node_modules/@badeball/cypress-cucumber-preprocessor/dist/plugin-event-handlers.js:343:43)
    at processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async Object.handler (/home/jenkins/.../cypress/plugins/index.ts:2:1865)

I have followed the workarounds documented in the event handlers guide and the issue #1046

This is my setup:

async function setupNodeEvents(
  cypressOn: Cypress.PluginEvents,
  config: Cypress.PluginConfigOptions,
): Promise<Cypress.PluginConfigOptions> {
  const on = cypressOnFix(cypressOn); // import cypressOnFix from 'cypress-on-fix';

  await addCucumberPreprocessorPlugin(on, config, {
    omitAfterSpecHandler: true,
  });

  plugins(on, config); // import plugins from 'cypress/plugins';

  cypressFailFast(on, config); // import cypressFailFast from 'cypress-fail-fast/plugin';

  return config;
}

In cypress/plugins file, I have a function to delete videos if there were no failures - Official Cypress Docs

export default (
  on: Cypress.PluginEvents,
  config: Cypress.PluginConfigOptions,
): void | Cypress.PluginConfigOptions => {
  on('after:spec', async (spec: Cypress.Spec, results: CypressCommandLine.RunResult) => {
    await afterSpecHandler(config, spec, results);

    if (results && results.video) {
      const failures = results.tests.some((test) =>
        test.attempts.some((attempt) => attempt.state === 'failed'),
      );

      if (!failures) {
        fs.unlinkSync(results.video);
      }
    }
  });
};

Enviroments:

Node version: 16
Operating system: Linux 
Browser: Electron

Plugins:

"@badeball/cypress-cucumber-preprocessor": "^21.0.0",
"@bahmutov/cypress-esbuild-preprocessor": "^2.2.3",
"cypress": "^13.15.0",
"cypress-fail-fast": "^7.1.1",
"cypress-on-fix": "^1.1.0",

I hope this help.

[badeball]

I hope this help.

Unfortunately, it doesn't. Aside from the somewhat similar wording of the error messages, each expectation-error usually represents completely different edge-cases, with uncomparable fixes. My advice is to open up a new ticket and provide a reproducible example, which illustrates your edge case, whatever that might be.

[czhang0405]

Unfortunately, it doesn't. Aside from the somewhat similar wording of the error messages, each expectation-error usually represents completely different edge-cases, with uncomparable fixes. My advice is to open up a new ticket and provide a reproducible example, which illustrates your edge case, whatever that might be.

I see, thanks for your fast response.

[badeball]

I've introduced a new flag in v23.2.0 to turn errors related to state tracking, as seen here, into soft errors - meaning that they won't halt execution, but rather an error is printed to stderr after the run.

This will hopefully ensure that underlying issues in user-code aren't masked and edge cases might reveal themselves. Thus possibly help users provide proper reproducible examples. Check the changelog for examples illustrating the configuration option.

However, due to lack of a reproducible example, I'm closing this issue. Feel free to open up another issue if anything changes in this regard.