Common Errors

The most frequently encountered checker and runtime errors, with explanations and fixes.

What you'll learn: How to diagnose and fix the errors you're most likely to hit.

Checker Errors

"reserved field name"

error: field `id` is a reserved system field
  --> module.grove:5:3

Cause: You declared a field using a reserved name. The fields pk, id, version, created_at, updated_at, created_by, and updated_by are managed by the runtime.

Fix: Choose a different field name.

// Wrong
record {
  kind "item"
  id: String        // reserved
}

// Right
record {
  kind "item"
  external_id: String
}

"multiple record declarations"

error: module can have at most one record declaration

Cause: You have more than one record { ... } block in the module (including across merged files).

Fix: Combine all fields into a single record block.

"unknown validate reference"

error: validate reference `check_title` not found
  --> module.grove:25:3

Cause: An action references validate check_title but no validate check_title { ... } declaration exists.

Fix: Either create the validate declaration or use inline validation.

// Option 1: Create the declaration
validate check_title {
  params.title != ""
}

// Option 2: Inline it
action create {
  validate check_title {
    params.title != ""
  }
  ...
}

"emit not allowed in this context"

error: emit is only allowed in action apply blocks

Cause: You used emit outside of an action's apply block -- in a function, lambda, event apply, or validate block.

Fix: Move the emit into an action's apply block.

"invalid state transition"

error: no state transition allows event `completed` from current state

Cause: The state machine doesn't define a transition for this event from the current state. For example, trying to emit completed when the status is open but the state machine only allows open -> in_progress.

Fix: Check your state machine transitions and ensure the event matches an allowed transition from the current state.

"for loop not allowed here"

error: for loops are only allowed in action apply blocks

Cause: You used a for loop outside of an action apply block.

Fix: Use list methods (.map(), .filter(), .find()) instead, or restructure your logic to use for inside an action apply.

"validate body must be boolean"

error: validate body must evaluate to a boolean expression

Cause: The expression in a validate block doesn't return a boolean.

Fix: Ensure the expression uses comparison or logical operators that produce a boolean.

// Wrong
validate check {
  params.title    // String, not Bool
}

// Right
validate check {
  params.title != ""
}

"upcast version ordering"

error: upcast source version must be lower than target version

Cause: upcast action create v2 -> v1 { ... } -- the source version is higher than the target.

Fix: Swap the versions. Upcasts always go from lower to higher.

Runtime Errors

"action not found"

The request specifies an action name that doesn't exist in the module.

Fix: Check the name field in your request JSON matches an action declared in the module.

"validation failed"

A validate block returned false.

Fix: Check the request params against the validation rules. The error message indicates which validate block failed.

"invariant violated"

After applying events, a record invariant evaluated to false.

Fix: The emitted events produced a record state that violates an invariant. Check the invariant condition and ensure your event data maintains it.