Guide
Gherkin syntax errors, explained in plain English
By Miftode Vasilica, maker of Gherkin Studio ·
A Gherkin parser error such as expected: #EOF, #TableRow, #DocStringSeparator, #StepLine… got 'this is a note' means one thing: on that line the parser found text it cannot place, and the names with a # are the kinds of line it would have accepted there. This page lists the messages the official Cucumber parser gives, what each one means, and the fix. Every message below was produced by running a broken file through @cucumber/gherkin version 42.
The message nobody reads twice
Ten minutes before a release, a build fails. The log says:
(4:5): expected: #EOF, #TableRow, #DocStringSeparator, #StepLine, #TagLine,
#ExamplesLine, #ScenarioLine, #RuleLine, #Comment, #Empty, got 'this is a note'
The person who wrote line 4 is a product owner. She added a note under a step. She is not going to read that message, and she should not have to.
It says something simple. (4:5) is line 4, column 5. Everything after expected: is a list of what may come after a step. got is what she typed.
How to read the list
| In the message | Means |
|---|---|
#FeatureLine |
a line starting with Feature: |
#RuleLine |
Rule: |
#ScenarioLine |
Scenario:, Scenario Outline: or Example: |
#ExamplesLine |
Examples: |
#StepLine |
a step: Given, When, Then, And, But |
#TableRow |
a table row, | like | this | |
#DocStringSeparator |
the """ that opens or closes a doc string |
#TagLine |
a tag, @like-this |
#Language |
the # language: xx header |
#Comment, #Empty |
a comment or an empty line |
#EOF |
the end of the file |
#Other |
free text, such as a description |
The errors, one by one
Text after a step
Feature: Password reset
Scenario: Link expires
Given I requested a reset link
this is a note
(4:5): expected: #EOF, #TableRow, #DocStringSeparator, #StepLine, #TagLine, #ExamplesLine, #ScenarioLine, #RuleLine, #Comment, #Empty, got 'this is a note'
Free text is allowed under Feature: and under Scenario:, before the first step. After a step it is not. Fix: make it a comment with #, or move it above the first step.
The file does not start with a feature
Scenario: Link expires
Given I requested a reset link
(1:1): expected: #EOF, #Language, #TagLine, #FeatureLine, #Comment, #Empty, got 'Scenario: Link expires'
Every file needs one Feature: line before anything else, except tags, comments and the language header. You get the same message again for each line that follows. Fix: add Feature: some name at the top. All the errors go at once.
Two features in one file
The same long message, ending in got 'Feature: B'. A file holds one feature. Fix: split it into two files, or turn the second Feature: into a Rule:.
A table row with a missing cell
Given these users exist
| name | role |
| Ana |
(5:7): inconsistent cell count within the table
Every row needs the same number of cells as the header. Fix: add the missing cell, even if it is empty: | Ana | |.
A doc string that never closes
(6:0): unexpected end of file, expected: #DocStringSeparator, #Other
The parser reached the end of the file while still inside a """ block. The line number is the last line of the file, not the line where the block opened, which is why this one is hard to find. Fix: search for """ and count them. There must be an even number.
A tag with nothing under it
(3:0): unexpected end of file, expected: #TagLine, #RuleLine, #Comment, #Empty
A tag has to sit above the thing it tags. A tag on the last line of a file tags nothing. Fix: delete it, or add the scenario it was meant for.
A language code that does not exist
(1:1): Language not supported: xx
Fix: use a code from the list of Gherkin languages, such as # language: fr.
The mistakes that give no error
Some typos are valid Gherkin. Scenario Link expires, with no colon, is read as description text. So is Givn I requested a link. The file parses, and the scenario you thought you wrote does not exist. These are covered in how to write Gherkin scenarios in a Jira story.
What Gherkin Studio shows instead
The editor in Gherkin Studio runs the same parser and rewrites the expected … got messages. For the first example above, the text under the editor is:
Line 4: Unexpected text "this is a note". Expected end of file, a table row (| … |), a doc string ("""), a step (Given/When/Then/And/But), a tag, Examples:, Scenario: or Rule:.
Click Line 4 and the cursor goes there. The table, doc string and language messages are shown as the parser writes them, with the line number.
A scenario with an error can still be saved, so half an idea is not lost. It is not pushed to Git until it parses.
Short answers
What does #EOF mean in a Gherkin error?
End of file. The parser is saying the file could also have stopped there.
Why do I get the same error on every line?
One early mistake, usually a missing Feature: line, makes every later line unexpected. Fix the first error and run again.
Does indentation matter in Gherkin?
No. Indentation is for people. The parser reads keywords.
Where Gherkin Studio fits
Gherkin Studio is a BDD app for Jira Cloud, built on Atlassian Forge. You can try the editor and its error messages on the home page, in the browser. The app is on the Atlassian Marketplace.