How do I read EK9 compiler error messages?

← Debugging and Troubleshooting · Ref: Q247

EK9 error messages follow a consistent format and can be displayed at multiple verbosity levels. Understanding the format helps you fix issues quickly.

ERROR MESSAGE FORMAT

The compiler first names the phase and the file, then reports each error on one line:

  EK9     : FULL_RESOLUTION: Errors in ./myfile.ek9
  EK9     : Error   : EXXXXX: 'token' on line L position C: message

For example, using a variable that was never declared:

  EK9     : Error   : E50001: 'unknownVar' on line 7 position 31: 'unknownVar': not resolved
             See: ek9 -h E50001

The token, line number and position tell you exactly where the error is, and the EXXXXX code uniquely identifies the error type (E50001 is 'not resolved'; E50030 is a different error, incompatible types).

VERBOSITY LEVELS

EK9 supports four error formats, controlled by -E0 through -E3. (-E4, -E5 and -E6 are not error formats: they print help and bootstrap summaries.)

-E0 (Minimal, the default): Single-line error messages with the error code, the token and its line and position. Best for experienced developers who know what the codes mean.

-E1 (Visual): Rust-style visual display with source code snippets and carets (^) pointing to the exact error location. Shows the surrounding code context. Recommended for daily development.

-E2 (Suggestions): Everything in -E1 plus 'Did you mean?' suggestions. When you misspell a variable or method name, the compiler uses fuzzy matching to suggest corrections.

-E3 (Full Explanations): Everything in -E2 plus detailed explanations suitable for beginners and AI tools. Includes diagnosis (what went wrong), rationale (why EK9 enforces this), and examples (how to fix it). Best for learning EK9.

-E4 is not an error format. 'ek9 -h -E4' prints a concise paradigm summary of EK9's key design decisions, and '-E5' adds the full AI bootstrap reference.

LOOKING UP ERROR CODES

Any error code can be looked up with:

  ek9 -h EXXXXX

This displays a detailed explanation of the error, what causes it, and how to fix it. Works offline, no internet needed.

MULTIPLE ERRORS

The compiler reports ALL errors it can find in a single pass, not just the first one. Fix errors from the top of the file downward, as later errors are sometimes caused by earlier ones.

See Q246 for debugging strategies. See Q248 for error code ranges and lookup. See Q252 for all compiler flags. See Q311 for the full catalog of quality error codes.

Example

defines module qa.debugging.errormessages

  defines class

    Temperature
      degrees <- Float()
      unit <- String()

      Temperature()
        ->
          initialValue as Float
          initialUnit as String
        require initialValue?
        require initialUnit?
        this.degrees :=: initialValue
        this.unit :=: initialUnit

      celsius() as pure
        <- rtn as Float: Float()
        if unit == "C"
          rtn: degrees
        else
          rtn: (degrees - 32.0) * 5.0 / 9.0

      operator $ as pure
        <- rtn as String: `${degrees} ${unit}`

      override operator ? as pure
        <- rtn as Boolean: degrees? and unit?

  defines program

    ErrorMessageDemo()
      stdout <- Stdout()

      // Create valid temperature
      reading <- Temperature(100.0, "C")
      stdout.println(`Temperature: ${reading}`)
      stdout.println(`In Celsius: ${reading.celsius()}`)

      // Demonstrate correct patterns that avoid common errors
      count <- 42
      stdout.println(`Count: ${count}`)

      // Correct type usage
      name <- "EK9"
      nameLength <- length name
      stdout.println(`${name} has ${nameLength} characters`)

      // Correct operator usage
      a <- 10
      b <- 20
      sum <- a + b
      stdout.println(`Sum: ${sum}`)

Common mistakes

E50060 — EK9 uses 'length' as a prefix operator, not a method call. The method 'length()' does not exist on String. See ek9 -h E50060 for details.

Incorrect:

name.size()

Correct:

length name

Coming from another language?

Java: javac shows file:line: error with no visual display, IDEs provide rich error display. Python: SyntaxError with caret, traceback for runtime errors. Rust: famously rich error messages with source snippets, suggestions, and explanations. Go: terse single-line errors. C++: notoriously verbose template errors, varies by compiler. Kotlin: similar to Java with better type inference errors. EK9: four error formats (-E0 to -E3) from minimal to full AI-friendly explanations, visual source snippets with carets, fuzzy suggestions, offline error code lookup.

Keywords: verbosity, read, error, migrate, debug, compile, lookup, format, E0, troubleshoot, E1, level, E2, E3, error-message, code, understand, diagnostic, message