Diagnosing Cucumber Glue Errors: A Step‑by‑Step Guide to Fix Missing Step Definitions

Recognizable Condition

During a test run you see messages such as:

Feature: User login
  Scenario: Successful login
    Given I open the login page
    When I enter valid credentials
    Then I should see the dashboard

Undefined steps:
  3 undefined steps found in 1 scenario (3.00s)
  1) Given I open the login page
  2) When I enter valid credentials
  3) Then I should see the dashboard

All steps are marked as undefined and no step definitions are executed.

Common Causes

Symptom	Probable Cause
All steps undefined	Glue package not scanned or step definitions not compiled
‘Could not find glue’ error	Runner’s glue attribute points to wrong package or missing
‘No matching step definitions’	Step annotations use wrong Gherkin keyword or regex mismatch
Feature file fails to parse	Malformed Gherkin (indentation, tabs, non‑ASCII quotes)
Build fails before test runner starts	Missing or incompatible cucumber‑java / cucumber‑junit dependencies

Diagnostic Checklist

1. Verify Maven/Gradle dependencies – ensure cucumber-java and cucumber-junit are present and the same major version.

   mvn dependency:tree | grep cucumber
   # or
   gradle dependencies | grep cucumber

2. Check test runner class – confirm it uses @RunWith(Cucumber.class) and the @CucumberOptions(glue = "com.myapp.steps") attribute.

   @RunWith(Cucumber.class)
   @CucumberOptions(
       features = "src/test/resources/features",
       glue = {"com.myapp.steps"},
       plugin = {"pretty"}
   )
   public class RunCucumberTest {}
   

3. Confirm step definition package – the package name in glue must match the package where step classes reside. On case‑sensitive OS, com.myapp.steps is different from com.MyApp.steps.

   package com.myapp.steps;
   
   public class LoginSteps { ... }
   

4. Validate step annotations – each method should be annotated with @Given, @When, or @Then and the expression must match the Gherkin step.

   @Given("I open the login page")
   public void openLoginPage() { ... }
   

5. Inspect Gherkin syntax – ensure Scenario headers are correctly indented, tabs are avoided, and quotes are plain ASCII.

   Scenario: Successful login
     Given I open the login page
     When I enter valid credentials
     Then I should see the dashboard
   

6. Run tests with pretty plugin – mvn test -Dtest=RunCucumberTest -Dplugin=pretty or gradle test --tests RunCucumberTest --info to see detailed output.
   • Look for lines like Undefined steps: or Could not find glue.
7. Check IDE integration – enable Cucumber plugin’s “Show Gherkin Outline” to cross‑check that each feature step is linked to a step definition.

Step‑by‑Step Fixes

1. Glue Package Mismatch

Update @CucumberOptions(glue = ...) to point to the correct package or add the missing package to the scan. If you have multiple packages, list them all:

@CucumberOptions(glue = {"com.myapp.steps", "com.myapp.moresteps"})

After change, clean and rebuild the project.

2. Missing or Incorrect @RunWith Annotation

Ensure the test runner extends Cucumber. In JUnit 4:

@RunWith(Cucumber.class)
public class RunCucumberTest {}

For JUnit 5 with Cucumber 8+, use @Cucumber from io.cucumber.junit.platform.engine.Cucumber and a @CucumberOptions annotation.

3. Step Annotation or Regex Mismatch

Verify that the regex in the annotation matches the Gherkin step text. Common pitfall: using a dash or special character in the step that isn’t escaped in the regex.

@When("I enter valid credentials")
public void enterCredentials() { ... }

Use .* or named groups only when necessary.

4. Gherkin File Encoding or Syntax

Open the feature file in a UTF‑8 editor without BOM. Replace tabs with spaces (two spaces per level). Verify that all quotes are straight double quotes (U+0022). If the file contains non‑ASCII characters, escape them or use unicode escape sequences.

5. Dependency Version Mismatch

Cucumber‑JVM 7.x and 8.x share the same package layout, but 9.x introduces a new cucumber-java8 module. Ensure all cucumber dependencies are the same major version. In Maven:

<dependency>
  <groupId>io.cucumber</groupId>
  <artifactId>cucumber-java</artifactId>
  <version>8.15.0</version>
</dependency>

6. IDE Plugin Mis‑configuration

Some IDEs cache step definitions. In IntelliJ, invalidate caches: File → Invalidate Caches / Restart. In VS Code, reload the window.

Escalation Criteria

1. If after the fixes the console still shows Undefined steps, run mvn dependency:tree to confirm no conflicting cucumber artifacts.
2. Check the classpath by printing System.getProperty("java.class.path") inside the test runner to ensure step classes are present.
3. If the runner cannot locate the glue, try adding classpath:/ to the glue attribute.
4. When using a build tool plugin (e.g., Gradle Cucumber plugin), verify that the plugin is applied and that it uses the same cucumber version.
5. If the issue persists, create a minimal reproducible example: a single feature file, one step definition, and a runner. If the minimal example works, the problem lies in project configuration or other tests.

Limitations

This guide covers the most common glue errors in Cucumber‑JVM 7/8. It does not address:

• Runtime errors inside step definitions (e.g., NullPointerException).
• Feature files that use Background or Scenario Outline with data tables that cause parsing errors.
• Cross‑project step reuse via @CucumberOptions(glue = "classpath:/…") in complex multi‑module setups.

Always validate the test output after each change. A clean run with no undefined steps confirms the issue is resolved.