# Diagnostic reference

> Interpret Alice compiler diagnostics and fix syntax, type, nil-safety, and race errors.

Canonical: https://alice-lang.org/documentation/reference/diagnostics/

[Documentation index](https://alice-lang.org/documentation/llms.txt) · [Complete book](https://alice-lang.org/llms-full.txt)

## Read a diagnostic

A compiler error identifies a code, a source location, and a message. The CLI adds a help hint where one is available.

```text
error[AL0202]: data race ...
  --> main.al:2:20
help: send the value through a Channel(T), use an Actor, or return it from the task
```

Start with the first meaningful error: later messages can be consequences of a missing token or unresolved type. .NET binding is mapped back to Alice file locations. Some underlying errors retain `CS` codes; common type errors use Alice's AL03xx codes and type names.

## Syntax and semantic checks

| Code   | Meaning                                 | Fix                                                                              |
| ------ | --------------------------------------- | -------------------------------------------------------------------------------- |
| AL0101 | Expected token, often a missing `end`   | Check the block opener and close it.                                             |
| AL0102 | Unexpected token, such as a stray `end` | Correct nesting or remove the extra token.                                       |
| AL0103 | Unterminated string or literal          | Close the string, interpolation, character, or attribute.                        |
| AL0201 | Non-exhaustive case                     | Handle missing enum variants or add an intentional fallback.                     |
| AL0202 | Possible data race                      | Return a result, communicate by channel/actor, or use supported synchronization. |
| AL0203 | Reassigning an immutable binding        | Keep `val` unchanged, or deliberately use a mutable local.                       |
| AL0204 | Cannot infer a type from `nil`          | Write a nullable annotation such as `name : String? = nil`.                      |
| AL0205 | Missing property/field type             | Add a type or initializer that determines it.                                    |
| AL0206 | Yield has no usable block parameter     | Declare a block signature or correct the supported yield form.                   |
| AL0001 | Other compiler error                    | Read the specific message and source context.                                    |

Do not fix AL0202 by hiding a shared write inside a helper. Fix the ownership or synchronization of the data. Read [race safety](https://alice-lang.org/documentation/concurrency/race-safety.md) for examples.

## Type checking

| Code   | Meaning                                 | Check                                                     |
| ------ | --------------------------------------- | --------------------------------------------------------- |
| AL0301 | Operator unavailable for these operands | Operand types and conversions                             |
| AL0302 | Undefined method/member                 | Spelling, receiver type, and package/namespace imports    |
| AL0303 | Undefined name                          | Local declaration and scope                               |
| AL0304 | Type mismatch                           | Expected type versus supplied value                       |
| AL0305 | Wrong argument type                     | Parameter order and signature                             |
| AL0306 | Wrong argument count                    | Required/default parameters and overload                  |
| AL0307 | Unknown type                            | `require`, `using`, restored references, and spelling     |
| AL0308 | Missing result on a return path         | Every branch in a value-returning method                  |
| AL0309 | Read before definite assignment         | Branches/loops that may skip initialization               |
| AL0310 | Possible nil                            | A checked branch or an intentionally justified `not_nil!` |
| AL0311 | Ambiguous call                          | Overload and lambda types                                 |
| AL0312 | Cannot infer generic arguments          | Explicit argument types/constraints                       |
| AL0313 | Inaccessible private member             | Public API boundary                                       |
| AL0314 | Read-only member                        | Getter versus property and intended mutation              |
| AL0315 | Instance required                       | Static versus instance call                               |
| AL0300 | Other type-checking error               | Message with Alice type names                             |

## A small debugging workflow

1. Run `alice check` to isolate compilation from execution.
2. Check the first location and its expected type.
3. Confirm packages are restored and project references built.
4. Reduce the example if the message appears wrong.
5. Use `alice emit file.al` to inspect lowering when relevant.

An apparent missing method can come from a missing assembly reference rather than a parser problem. Use `alice install` and verify the manifest before rewriting valid source.

## CLI errors and languages

Usage errors print a hint and normally exit with 2; missing files and build/test failures normally exit with 1. Internal failures exit with 70. `--verbose` provides internal details when reporting a bug.

Set `--lang en`, `--lang pt`, or `--lang es`, or use `ALICE_LANG`. The default follows the OS UI culture. Include the exact command, Alice version, and minimal source when reporting a diagnostic issue.

## Continue reading

- Previous: [MSBuild integration](https://alice-lang.org/documentation/tools/sdk.md)
- Next: [Feature status and boundaries](https://alice-lang.org/documentation/reference/feature-status.md)