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

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.

Spec rules: S3.1 and S3.3.

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:

fails with E0008Open in playground
- R9: The app saves every change.

Give the rule a keyword:

exampleOpen in playground
- 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:

fails with E0009Open in playground
- R1.: The app MUST save every change.

Remove the full stop at the end:

exampleOpen in playground
- 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:

fails with E0010Open in playground
- R1: The app MUST save every change.
- R1: The app MUST sync every change.

Give the second rule a new ID:

exampleOpen in playground
- 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:

fails with E0011Open in playground
---
Source: support tickets 4411 and 4502
---

- The app MUST retry a failed send.

Write the key in lowercase:

exampleOpen in playground
---
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:

fails with E0012Open in playground
- The app MUST save and SHOULD sync.

Split it into two rules, one keyword each:

exampleOpen in playground
- 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:

fails with E0014Open in playground
- The app MUST.

Write what the system must do:

exampleOpen in playground
- 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.

Spec rules: S6.5 and S6.15.

This raises it:

fails with E0015Open in playground
- WHEN the user saves, the app MUST write the file.

Write THEN before the subject:

exampleOpen in playground
- 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:

fails with E0016Open in playground
- THEN the app MUST write the file.

Remove THEN, or add the condition it follows:

exampleOpen in playground
- 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.

Spec rules: S6.8 and S6.9.

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:

fails with E0018Open in playground
- R1: The client MUST send every body type in table T3. [table T3]

Add the heading and the table, in the same file:

exampleOpen in playground
- 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:

fails with E0019Open in playground
- GIVEN the user is signed in, WHEN they save, THEN the app MUST sync.

Use WHILE for the state:

exampleOpen in playground
- 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:

fails with E0020Open in playground
- 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:

exampleOpen in playground
- 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:

fails with E0020Open in playground
- Logging every key press is not RECOMMENDED.

Write NOT RECOMMENDED in capitals, with one space, or use SHOULD NOT:

exampleOpen in playground
- 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:

fails with E0021Open in playground
- The app MAY not sync on a metered network.

If it is not allowed, use MUST NOT:

exampleOpen in playground
- 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.

Spec rules: S8.5 and S8.8.

This raises it:

fails with E0022Open in playground
- Sync is OPTIONAL to run on a metered network.

Use MAY:

exampleOpen in playground
- The app MAY sync on a metered network.

Words after REQUIRED raise it too:

fails with E0022Open in playground
- Logs are REQUIRED for audits.

Use the verb of the same strength with a response, or write "to" and a response:

exampleOpen in playground
- 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:

fails with E0023Open in playground
- R1: The app MUST save every change. [proposed] [dropped]

Keep the one that is true now. Git's history keeps the earlier one:

exampleOpen in playground
- 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:

fails with E0024Open in playground
- R1: The app MUST save every change. [accepted]

Remove the tag:

exampleOpen in playground
- 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:

fails with E0027Open in playground
- R7: The app MUST retry a failed send. [from R3]

Point to a rule that exists:

exampleOpen in playground
- 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:

fails with E0028Open in playground
- R1: The app MUST keep logs.
- R2: The app MUST NOT keep logs.

Decide which one holds, and drop or remove the other:

exampleOpen in playground
- 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:

fails with E0029Open in playground
When the user saves the app shall write the file.

The comma here comes before the second condition, so it does not end it:

fails with E0029Open in playground
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:

exampleOpen in playground
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:

fails with E0031Open in playground
- WHEN the user saves, THEN MUST write the file.

Write the system before the verb:

exampleOpen in playground
- 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:

fails with E0034Open in playground
- WHILE offline, THEN WHEN the user saves, THEN the app MUST queue the change.

In classic EARS too:

fails with E0034Open in playground
- Then, when asked, the app shall save the file.

Write every condition first, then THEN once; in classic EARS, "then" is optional:

exampleOpen in playground
- 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:

fails with E0035Open in playground
- Only WHERE sync is on, THEN the app MUST queue the change.

In classic EARS too:

fails with E0035Open in playground
- Only, when asked, the app shall save the file.

Move the words into a condition or the response, or remove them:

exampleOpen in playground
- 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:

fails with E0035Open in playground
- The app, while offline, shall queue every change.
exampleOpen in playground
- 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:

fails with E0036Open in playground
- The app MUST not delete a file without asking.

If the rule forbids, write the keyword in capitals, with one space:

exampleOpen in playground
- 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:

fails with E0036Open in playground
- 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":

exampleOpen in playground
- 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:

example, with a warningOpen in playground
- The app must save every change.

A paragraph with a structure word gets the same warning:

example, with a warningOpen in playground
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:

exampleOpen in playground
- 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:

example, with a warningOpen in playground
- WHILE offline, AND a change is queued, THEN the app MUST retry it.

Repeat the condition word:

exampleOpen in playground
- 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:

example, with a warningOpen in playground
- The app MUST save AND sync every change.

Write the word in lowercase, or split the rule:

exampleOpen in playground
- 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:

example, with a warningOpen in playground
- After a save, the app MUST sync the file.

Write the condition with a condition word and THEN:

exampleOpen in playground
- 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:

example, with a warningOpen in playground
- 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:

exampleOpen in playground
- 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:

example, with a warningOpen in playground
- WHILE offline, WHEN a request is sent, THEN the app MUST queue it.

Add a table of the cases, or split the rule:

exampleOpen in playground
- 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:

example, with a warningOpen in playground
- R1: The app MUST save every change.
- The app MUST sync every change.

Give it an ID that has not been used before:

exampleOpen in playground
- 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:

example, with a warningOpen in playground
- The app MUST export the file when the user asks.

Move the condition to the front:

exampleOpen in playground
- 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.