Errors and warnings
Every error and warning the compiler reports has a code, such as E0012 in
error[E0012]. A code that starts with E is an error: the checks fail. A
code that starts with W is a warning: the checks pass, unless ears check is
run with --deny warnings. ears explain E0012 prints the section for one
code. Numbers missing from the list are not in use.
Each section says what the code means, why it is reported, and the rule in the spec it comes from. Then it shows a mistake that raises the code, and what to write instead. Every example on this page is checked by the compiler's tests.
- E0002 unknown line in ears.mod
- E0003 ears.mod must hold exactly one earslang line
- E0004 unknown earslang version
- E0005 spelling is must or shall
- E0006 unknown fence attribute
- E0007 a fence takes one attribute
- E0008 an ID with no keyword
- E0009 invalid ID
- E0010 an ID is used twice
- E0011 a front matter line is "key: value"
- E0012 two keywords in one rule
- E0014 a rule with no response
- E0015 THEN is required after a condition
- E0016 THEN with no condition
- E0017 subject is not a declared system
- E0018 a [table] tag names no heading with a table under it
- E0019 GIVEN is not a structure word
- E0020 an adjective must follow is or are
- E0021 "MAY NOT" is not a keyword
- E0022 words that do not fit the adjective form
- E0023 more than one status tag
- E0024 unknown tag
- E0027 a from tag names no rule
- E0028 two rules contradict each other
- E0029 cannot tell where the subject starts
- E0031 a rule with no subject
- E0032 layout is collapse or keep
- E0033 unknown rewrite
- E0034 a condition after THEN
- E0035 words before the first condition
- E0036 a keyword followed by "not" that is not part of it
- W0001 lowercase must or shall in a list item or a paragraph
- W0002 AND or BUT in capitals
- W0003 a comma in the subject
- W0004 conditions out of the usual order
- W0005 two or more conditions and no [table] tag
- W0007 a system is declared twice
- W0008 a rule with no ID among rules that have one
- W0009 "when", "whenever", "while" or "if" in the response may hide a condition
E0002: unknown line in ears.mod
ears.mod holds six kinds of line: earslang <version>, spelling must or
spelling shall, layout collapse or layout keep, fix-skip and the
rewrites to skip, system <name>, and comments that start with #. Blank
lines are allowed. A later spelling or layout line replaces an earlier
one. Any other line is an error, so a misspelt setting is not silently
ignored.
Spec rule: S2.5.
This ears.mod raises it, because of the colon:
earslang 0.1
system: the app
Write the setting's name, a space, and its value:
earslang 0.1
system the app
E0003: ears.mod must hold exactly one earslang line
ears.mod names the version of earslang the project is written in, as
go.mod names a Go version. It holds exactly one earslang line: with none,
or with more than one, it is an error.
Spec rule: S2.1.
This ears.mod raises it, because it has no earslang line:
spelling shall
Add one line with the version. ears init writes it in a new project:
earslang 0.1
spelling shall
E0004: unknown earslang version
The earslang line names a version this compiler does not know. It is either
misspelt, or newer than the compiler. The help lists the versions the
compiler knows.
Spec rule: S2.6.
This ears.mod raises it:
earslang 1.0
Write a version the compiler knows, or install a newer compiler:
earslang 0.1
E0005: spelling is must or shall
The spelling line takes one of two values, in lowercase: must or
shall. It decides how ears fix and the markdown, HTML and Gherkin exports
write the keywords. Both spellings are accepted in rules either way.
Spec rule: S2.2.
This ears.mod raises it:
earslang 0.1
spelling SHALL
Write the value in lowercase:
earslang 0.1
spelling shall
E0006: unknown fence attribute
An ears fence takes one attribute after a comma: example, compile_fail
or ignore. A compile_fail attribute may be followed by a comma and one
code, such as E0012. Any other attribute is an error, so a misspelt one is
not silently ignored.
This markdown file raises it, because example is misspelt:
```ears,exmaple
- The app MUST save every change.
```
Spell the attribute as the list above gives it:
```ears,example
- The app MUST save every change.
```
E0007: a fence takes one attribute
An ears fence takes at most one attribute. compile_fail with a code, as
in ears,compile_fail,E0012, counts as one.
Spec rule: S3.2.
This markdown file raises it:
```ears,example,ignore
- The app MUST save.
```
Keep the one you mean. ignore leaves the block unread; example checks it:
```ears,example
- The app MUST save.
```
E0008: an ID with no keyword
A list item or paragraph line that starts with an ID, such as R9:, is a
rule, and a rule needs a keyword: MUST, SHOULD, MAY or another keyword of
BCP 14, in capitals, or, in a rule with no structure word, a lowercase
"shall". This rule has an ID and no keyword, so the compiler cannot tell its
strength. A lowercase "must" does not count: in lowercase it is ordinary
English.
Spec rule: S4.2.
This raises it:
- R9: The app saves every change.Give the rule a keyword:
- R9: The app MUST save every change.If it is prose and not a rule, remove the ID.
E0009: invalid ID
An ID starts with a letter, holds at least one digit, and holds only letters,
digits, hyphens, underscores and full stops. It does not end with a full
stop. R7, FR-001 and APP-512.1 are IDs. Text such as 1R: that breaks
the other rules is not read as an ID; it stays in the sentence.
Spec rule: S4.7.
This raises it:
- R1.: The app MUST save every change.Remove the full stop at the end:
- R1: The app MUST save every change.E0010: an ID is used twice
Two rules in one project have the same ID, so nothing can tell which one a
tag such as [from R1] means. The help names the other place. Do not give a
used ID to another rule, even after its rule is dropped or deleted; the
compiler sees only the IDs in the files.
Spec rule: S4.8.
This raises it:
- R1: The app MUST save every change.
- R1: The app MUST sync every change.Give the second rule a new ID:
- R1: The app MUST save every change.
- R2: The app MUST sync every change.E0011: a front matter line is "key: value"
Front matter is the lines between two --- lines at the top of a .ears
file or an ears block. Each line is a key, a colon and a value. A key
starts with a lowercase letter, followed by lowercase letters, digits,
hyphens and underscores. The compiler checks the key's form, not its value.
An indented line continues the value above it.
Spec: §5 (rules and prose).
This raises it:
---
Source: support tickets 4411 and 4502
---
- The app MUST retry a failed send.Write the key in lowercase:
---
source: support tickets 4411 and 4502
---
- The app MUST retry a failed send.E0012: two keywords in one rule
A rule holds one keyword, so that each duty can be tested, changed and
dropped on its own. This rule holds two. The marks under the line show the
first with - and the second with ^.
Spec rule: S6.3.
This raises it:
- The app MUST save and SHOULD sync.Split it into two rules, one keyword each:
- The app MUST save.
- The app SHOULD sync.E0014: a rule with no response
A rule with a verb, such as MUST, says what the system does after the verb. This rule ends at the verb, so it says nothing.
Spec rule: S6.4.
This raises it:
- The app MUST.Write what the system must do:
- The app MUST save every change.E0015: THEN is required after a condition
A rule with a condition (WHERE, WHILE, WHEN or IF) writes THEN before its
subject, so that the end of the condition is clear. When a comma comes before
the keyword, the help shows the sentence with THEN after the last comma; with
no comma, it shows the standard form with THEN. ears fix does not add it,
because that comma may belong to the condition.
THEN may be left out when ears.mod declares systems and the words before
the keyword end with one of them: that system is the subject, and ears fix
adds THEN before it.
This raises it:
- WHEN the user saves, the app MUST write the file.Write THEN before the subject:
- WHEN the user saves, THEN the app MUST write the file.Or declare the system in ears.mod with system the app, and the rule
passes as it is.
E0016: THEN with no condition
THEN starts the subject after a condition. This rule has THEN and no condition before it.
Spec rule: S6.6.
This raises it:
- THEN the app MUST write the file.Remove THEN, or add the condition it follows:
- WHEN the user saves, THEN the app MUST write the file.E0017: subject is not a declared system
When ears.mod declares systems with system lines, the subject of every
rule with a verb is one of them. Capital letters do not matter. This catches
a rule written for a system that does not exist, or one whose name is
misspelt.
The project's ears.mod:
earslang 0.1
system the app
This markdown file in that project raises it:
```ears
- The server MUST log every error.
```
Use a declared system as the subject, or declare the new one in ears.mod
with system the server:
```ears
- The app MUST log every error.
```
E0018: a [table] tag names no heading with a table under it
This rule's [table T3] tag names no heading in the same file with a pipe
table under it. The tag points to a heading whose first word is T3, such as
### T3 Body types. ### T3: Body types does not match, since its first
word is T3:. The compiler checks only that the table is there, not what is
in it.
Spec rule: S6.13.
This raises it:
- R1: The client MUST send every body type in table T3. [table T3]Add the heading and the table, in the same file:
- R1: The client MUST send every body type in table T3. [table T3]
### T3 Body types
| Type |
|---|
| JSON |
| form |E0019: GIVEN is not a structure word
GIVEN comes from Gherkin, where it often states a past action ("Given I added an item"). That is not a state, so earslang does not accept it. Use WHILE for a state that holds, and WHEN for an event.
Spec rule: S5.4.
This raises it:
- GIVEN the user is signed in, WHEN they save, THEN the app MUST sync.Use WHILE for the state:
- WHILE the user is signed in, WHEN they save, THEN the app MUST sync. [table T1]
### T1 Sync
| Signed in | Saves | Syncs |
|---|---|---|
| yes | yes | yes |
| yes | no | no |
| no | yes | no |
| no | no | no |A rule with two conditions takes a [table] tag (W0005), so the fix has one.
E0020: an adjective must follow is or are
REQUIRED, RECOMMENDED, NOT RECOMMENDED and OPTIONAL are adjectives. They follow "is" or "are", as BCP 14 writes them: "A title is REQUIRED." Anywhere else the compiler cannot read the rule.
Spec rule: S8.3.
This raises it:
- Every page has a REQUIRED title.Write "X is REQUIRED", or use the verb of the same strength: MUST for REQUIRED, SHOULD for RECOMMENDED, SHOULD NOT for NOT RECOMMENDED and MAY for OPTIONAL:
- Every page MUST have a title.When the word "not" stands before the adjective, the help keeps it, so the rule is not reversed. "not RECOMMENDED" in lowercase, or with two spaces, a tab or a hyphen between the words, is not the keyword NOT RECOMMENDED:
- Logging every key press is not RECOMMENDED.Write NOT RECOMMENDED in capitals, with one space, or use SHOULD NOT:
- Logging every key press is NOT RECOMMENDED."NOT REQUIRED" and "NOT OPTIONAL" are not keywords. For "not required", use MAY or OPTIONAL; for "not optional", use REQUIRED or MUST.
E0021: "MAY NOT" is not a keyword
BCP 14 does not define "MAY NOT", and English reads it two ways: "is not allowed to" and "is allowed not to". Write the one you mean.
Spec rule: S8.4.
This raises it:
- The app MAY not sync on a metered network.If it is not allowed, use MUST NOT:
- The app MUST NOT sync on a metered network.If it is allowed, use MAY with a response that says what is allowed: "The app MAY skip the sync on a metered network."
E0022: words that do not fit the adjective form
OPTIONAL is an adjective with nothing after it: "A subtitle is OPTIONAL." The form "OPTIONAL to" does not exist in BCP 14.
The other adjectives end the rule or take "to" and a response: "Logs are
REQUIRED." or "The user is REQUIRED to confirm." Other words after an
adjective, as in "Logs are REQUIRED for audits.", fit neither form. Read
without them, the rule would lose them, and ears fix would drop them, so
they are an error too. The help keeps the words. When they hold a condition
word in capitals, as in "Saving is REQUIRED WHEN asked.", the help puts the
condition first ("WHEN asked, THEN Saving MUST ."), since a
condition word after the keyword is read as part of the response.
This raises it:
- Sync is OPTIONAL to run on a metered network.Use MAY:
- The app MAY sync on a metered network.Words after REQUIRED raise it too:
- Logs are REQUIRED for audits.Use the verb of the same strength with a response, or write "to" and a response:
- The app MUST keep logs for audits.
- Logs are REQUIRED to be kept for audits.E0023: more than one status tag
A rule has at most one status: none (in force), [proposed] or [dropped].
This rule has two.
Spec rule: S10.2.
This raises it:
- R1: The app MUST save every change. [proposed] [dropped]Keep the one that is true now. Git's history keeps the earlier one:
- R1: The app MUST save every change. [dropped]E0024: unknown tag
The tags are [proposed], [dropped], [from <ID>, …] and
[table <name>]. Any other text in square brackets at the end of a rule is
an error. [accepted] is refused too: a rule is in force unless a tag says
otherwise, so a rule in force has no tag. [replaced-by <ID>] is not a tag
in 0.1: reword the rule in place and keep its ID, or tag the old rule
[dropped] and write the new one.
Spec rule: S10.3.
This raises it:
- R1: The app MUST save every change. [accepted]Remove the tag:
- R1: The app MUST save every change.E0027: a from tag names no rule
[from R3] says a rule was derived from rule R3. There is no rule R3 in the
project. Evidence from outside the project, such as an issue or an interview,
goes in the front matter's source: line instead.
Spec rule: S10.6.
This raises it:
- R7: The app MUST retry a failed send. [from R3]Point to a rule that exists:
- R3: The app MUST NOT lose a change.
- R7: The app MUST retry a failed send. [from R3]E0028: two rules contradict each other
Two rules in force have the same subject, the same conditions, the same response and the same strength, and one is the negative of the other. Both cannot hold. The check compares text after normalising spaces and capitals, so it finds exact contradictions only; a contradiction in meaning stays with review.
Spec rule: S11.2.
This raises it:
- R1: The app MUST keep logs.
- R2: The app MUST NOT keep logs.Decide which one holds, and drop or remove the other:
- R1: The app MUST keep logs. [dropped]
- R2: The app MUST NOT keep logs.E0029: cannot tell where the subject starts
A rule with no structure word is read as classic EARS. There, the subject
starts after "then"; otherwise at a system declared in ears.mod that the
words before the keyword end with; otherwise after the last comma before the
keyword, when that comma follows every condition. A comma before a condition
word only opens the condition. This rule has a condition and none of the
three, so the compiler cannot tell where the condition ends.
Spec rule: S7.4.
This raises it:
When the user saves the app shall write the file.The comma here comes before the second condition, so it does not end it:
When the file is saved, if the user asked the app shall sync it.Put a comma after the condition, or declare the system in ears.mod with
system the app. Or write it with structure words and THEN:
WHEN the user saves, THEN the app MUST write the file.E0031: a rule with no subject
A rule with a verb, such as MUST, says who must act before the verb. This rule has nothing there: the rule starts with the verb, or the verb comes straight after THEN or after the last comma of a classic rule.
Spec rule: S6.16.
This raises it:
- WHEN the user saves, THEN MUST write the file.Write the system before the verb:
- WHEN the user saves, THEN the app MUST write the file.E0032: layout is collapse or keep
The layout line takes one of two values, in lowercase: collapse or
keep. It decides how ears fix lays out a rule it rewrites: on one line
(collapse, the default), or on the lines it was written on (keep).
Spec rule: S2.8.
This ears.mod raises it:
earslang 0.1
layout lines
Write one of the two values:
earslang 0.1
layout keep
E0033: unknown rewrite
A fix-skip line names the rewrites of ears fix that the project does not
want, each by its code or its name: F0001 classic, F0002 keyword, F0003
adjective, F0004 comma, F0005 then, F0006 full-stop and F0007 and.
This line names one that does not exist, so it would skip nothing.
Spec rule: S2.9.
This ears.mod raises it:
earslang 0.1
fix-skip commas
Use a code or a name from the list:
earslang 0.1
fix-skip comma F0006
E0034: a condition after THEN
THEN comes once, after the last condition and before the subject. This rule has a condition word after THEN, so where the conditions end and the subject starts is not clear.
Spec rule: S6.17.
This raises it:
- WHILE offline, THEN WHEN the user saves, THEN the app MUST queue the change.In classic EARS too:
- Then, when asked, the app shall save the file.Write every condition first, then THEN once; in classic EARS, "then" is optional:
- When asked, the app shall save the file.
- WHILE offline, WHEN the user saves, THEN the app MUST queue the change. [table T1]
### T1 Saving while offline
| Offline | Saves | Queues the change |
|---|---|---|
| yes | yes | yes |
| yes | no | no |
| no | yes | no |
| no | no | no |E0035: words before the first condition
A rule with a condition starts with it, in capitals or in classic EARS.
Words before the first condition word are in no part of the rule: not a
condition, not the subject and not the response. Left there, they would be
read as nothing, and ears fix would drop them.
Spec rule: S6.18.
This raises it:
- Only WHERE sync is on, THEN the app MUST queue the change.In classic EARS too:
- Only, when asked, the app shall save the file.Move the words into a condition or the response, or remove them:
- WHERE sync is on, THEN the app MUST queue the change.
- When asked, the app shall save the file.When the words are the subject, and no subject follows the conditions, the help shows the rule with the subject after them:
- The app, while offline, shall queue every change.- While offline, the app shall queue every change.E0036: a keyword followed by "not" that is not part of it
The keyword is MUST NOT, SHALL NOT or SHOULD NOT in capitals, or "shall
not" in lowercase in classic EARS. Its two words are separated by one space;
any Unicode space character, such as a no-break space, counts as a space.
E0036 is reported when MUST, SHALL, SHOULD or a classic "shall" is followed
by "not" written another way: in another case ("MUST not", "shall NOT"),
after spacing other than one space, such as two spaces, a tab or a
character that shows nothing, joined to it by a hyphen, a dash, an
underscore or a slash ("MUST-NOT"), or with markdown emphasis between them
(MUST **NOT**, MUST *not*). ears 0.1.0 read such a rule by its keyword
alone, with "not" in the response, which may say the opposite of what was
meant; ears 0.1.1 reports the error. A dash with a blank on each side is
reported too: "MUST — not the user — approve" and "MUST — not ever — store"
look alike, and only the writer knows which one is meant.
The message quotes what was written, and names the spaces, the joiner or the asterisks when they are not one space. With emphasis, the help says to write the keyword without it.
Spec rule: S8.7.
This raises it:
- The app MUST not delete a file without asking.If the rule forbids, write the keyword in capitals, with one space:
- The app MUST NOT delete a file without asking.The same "not" may also belong to the response, as in "The app MUST not only save the file but also sync it." The compiler cannot tell which is meant, so it reports the error here too:
- The app MUST not only save the file but also sync it.If the rule does not forbid, reword it so that MUST is not followed by "not":
- The app MUST save the file and also sync it.W0001: lowercase must or shall in a list item or a paragraph
A list item or a paragraph with no keyword is prose. Lowercase "must" is never a keyword, and lowercase "shall" is one only in a rule with no structure word; otherwise both are ordinary English (RFC 8174). In a list item, or in a paragraph that holds a structure word such as WHEN or THEN, that is often a rule written by mistake, so the compiler warns. A paragraph with no structure word is read as prose with no warning.
Spec rule: S4.5.
This passes, with the warning:
- The app must save every change.A paragraph with a structure word gets the same warning:
WHEN the user saves, THEN the app must write the file.If the list item or the paragraph is a rule, write the keyword in capitals:
- The app MUST save every change.
WHEN the user saves, THEN the app MUST write the file.If it is prose, reword it or leave the warning.
W0002: AND or BUT in capitals
AND and BUT are not structure words. In capitals they are read as ordinary text, which may not be what the writer meant.
In a condition, AND usually starts a second condition. Repeat the condition
word in its place. ears fix does this when AND or BUT follows a comma or
starts a line.
Spec rule: S5.5.
This passes, with the warning:
- WHILE offline, AND a change is queued, THEN the app MUST retry it.Repeat the condition word:
- WHILE offline, WHILE a change is queued, THEN the app MUST retry it. [table T1]
### T1 Retry
| Offline | A change is queued | Retries it |
|---|---|---|
| yes | yes | yes |
| yes | no | no |
| no | yes | no |
| no | no | no |A rule with two conditions takes a [table] tag (W0005), so the fix has one.
In a response, AND often joins two duties that belong in two rules. This passes, with the warning:
- The app MUST save AND sync every change.Write the word in lowercase, or split the rule:
- The app MUST save every change.
- The app MUST sync every change.W0003: a comma in the subject
The subject is the text between THEN and the keyword, or everything before the keyword when there is no condition. A comma there is usually a condition written without a condition word (WHERE, WHILE, WHEN or IF).
Spec rule: S6.7.
This passes, with the warning:
- After a save, the app MUST sync the file.Write the condition with a condition word and THEN:
- WHEN a save ends, THEN the app MUST sync the file.W0004: conditions out of the usual order
The usual order of conditions is WHERE, then WHILE, then WHEN or IF: the feature, then the state, then the event. Rules that keep one order are easier to compare.
Spec rule: S6.10.
This passes, with the warning:
- WHEN a request is sent, WHILE offline, THEN the app MUST queue it. [table T1]
### T1 Queue
| Offline | A request is sent | Queues it |
|---|---|---|
| yes | yes | yes |
| yes | no | no |
| no | yes | no |
| no | no | no |Put the state first:
- WHILE offline, WHEN a request is sent, THEN the app MUST queue it. [table T1]
### T1 Queue
| Offline | A request is sent | Queues it |
|---|---|---|
| yes | yes | yes |
| yes | no | no |
| no | yes | no |
| no | no | no |W0005: two or more conditions and no [table] tag
A rule with two or more conditions says only what happens when all of them
hold. The other cases are easy to forget. A table with a row for each case,
named with [table <name>], shows what happens in each. Declared states and
full truth tables are not in 0.1.
Spec rule: S6.11.
This passes, with the warning:
- WHILE offline, WHEN a request is sent, THEN the app MUST queue it.Add a table of the cases, or split the rule:
- WHILE offline, WHEN a request is sent, THEN the app MUST queue it. [table T1]
### T1 Queue
| Offline | A request is sent | Queues it |
|---|---|---|
| yes | yes | yes |
| yes | no | no |
| no | yes | no |
| no | no | no |W0007: a system is declared twice
ears.mod declares the same system twice. Capital letters do not matter, so
the app and The App are the same system.
Spec rule: S9.1.
This ears.mod passes, with the warning:
earslang 0.1
system the app
system The App
Remove one of the lines:
earslang 0.1
system the app
W0008: a rule with no ID among rules that have one
Another rule in this file has an ID, and this one does not. Nothing can cite
it, and ears diff can follow it only by its text. Usually the ID was
forgotten.
Spec rule: S4.15.
This passes, with the warning:
- R1: The app MUST save every change.
- The app MUST sync every change.Give it an ID that has not been used before:
- R1: The app MUST save every change.
- R2: The app MUST sync every change.W0009: "when", "whenever", "while" or "if" in the response may hide a condition
A lowercase "when", "whenever", "while" or "if" after the keyword is usually a condition written at the end of the rule. Conditions go at the front, in capitals, so that every rule shows them in the same place.
Spec rule: S6.14.
This passes, with the warning:
- The app MUST export the file when the user asks.Move the condition to the front:
- WHEN the user asks, THEN the app MUST export the file.If the word is not a condition, reword it: "check whether", not "check if".
The explanations on this page come from the ears repository, under the Apache License 2.0.