> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sensecode.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Reference

> The complete error hierarchy, what each type means, and how the CLI presents them.

## The hierarchy

Every failure Sense can raise is a `SenseError` subclass, each carrying a
source line number when one is known:

<Frame>
  ```txt theme={null}
  SenseError
    SenseSyntaxError    lexer or parser: malformed source
    SenseNameError      an identifier isn't defined in the current scope
    SenseTypeError      a value doesn't match a declared type annotation
    SenseRuntimeError   everything else at runtime
    SenseImportError    module resolution / circular import failures
    SensePolicyError    an Action's required capability was denied
    SenseApprovalError  an Action declared `requires approval` was
                        committed before <action>.approve() was called
  ```
</Frame>

<Note>
  A Sense program should never surface a raw Python traceback for a
  user-level mistake. Every error path in the interpreter is designed to
  raise one of these, with a message that says what went wrong and, where
  useful, what to do about it.
</Note>

## How the CLI presents them

```bash theme={null}
sense run broken.sns
```

```txt theme={null}
SenseError: [line 3] cannot assign value of type String to 'x: Int'
```

exit code `1`. A `RecursionError` (Python's own stack-overflow signal, for
deeply recursive Sense programs) is caught separately and presented as
`SenseError: maximum recursion depth exceeded` rather than a raw traceback.

## Errors with a distinct "did you mean" message

A handful of lexer errors are deliberately more specific than "unexpected
character," aimed at people (and LLMs) whose habits default to another
language's syntax:

<Frame>
  | You typed                                      | You get                                                                                     |
  | ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
  | `{` or `}`                                     | "Sense uses indentation for blocks, not `{ }` — write `:` then an indented block instead"   |
  | `;`                                            | "semicolons aren't used in Sense — start a new line instead"                                |
  | `!` (alone)                                    | "'!' is not an operator in Sense — use 'not' for negation and '!=' for not-equal"           |
  | a bare `name(...) returns Type:` with no `def` | "function declarations need 'def' -- e.g. 'def name(...) -> Type:'"                         |
  | `name(...): ... compensate:`                   | "'compensate' is now spelled 'rollback' -- rename this block's leading word to 'rollback:'" |
  | a tab used for indentation                     | "tabs are not allowed for indentation — use spaces"                                         |
</Frame>

## Common runtime errors, by cause

<AccordionGroup>
  <Accordion title="Type mismatch on a typed declaration or function boundary">
    `x: Int = "nope"`, or calling `f(a: Int)` with a `String`, or a function
    declared `returns Int` that returns a `String`. See
    [Values & Types](/language/values-and-types#type-annotations-are-a-runtime-check-not-static-inference).
  </Accordion>

  <Accordion title="Undefined variable">
    Reading a name nothing in the enclosing scope chain ever bound. See
    [Variables & Scope](/language/variables-and-scope).
  </Accordion>

  <Accordion title="Division or modulo by zero">
    `1 / 0` and `1 % 0` both raise — Sense never returns `inf`/`nan` silently.
  </Accordion>

  <Accordion title="Wrong number of arguments">
    Every declared function/action parameter must be supplied exactly
    once per call — no defaults, no variadic user-defined functions yet.
  </Accordion>

  <Accordion title="Action lifecycle violations">
    `.commit()` before `.verify()`, verifying or committing twice, calling
    `start()` on an already-started agent, `resume()` on a non-paused
    agent — see [Actions](/safety/actions) and
    [Pause & Resume](/ai-native/pause-resume).
  </Accordion>

  <Accordion title="Policy denial">
    `SensePolicyError` specifically — an action's `requires` capability was
    denied by the nearest applicable `policy` rule. See
    [Policy](/safety/policy).
  </Accordion>

  <Accordion title="Missing approval">
    `SenseApprovalError` specifically — an action declared `requires
            approval` was `.commit()`-ted before `<action>.approve()` was ever
    called. See [Actions](/safety/actions).
  </Accordion>

  <Accordion title="Circular or missing import">
    `SenseImportError`, naming the cycle or the resolved path that wasn't
    found. See [Modules](/language/modules).
  </Accordion>
</AccordionGroup>

## Continue

<CardGroup cols={2}>
  <Card title="Builtins reference" icon="function" href="/reference/builtins">
    What each builtin raises and when.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/reference/cli">
    How `sense run`/`sense repl` behave around errors.
  </Card>
</CardGroup>