Error Registry

In traditional Node.js or Python environments, errors often manifest as cryptic stack traces referencing files buried ten directories deep inside a node_modules folder.

Carotene errors are different. Because the language is a strictly typed architectural blueprint, errors are designed to be immediately actionable. When the compiler or the Vapor Sandbox catches a failure, it tells you exactly which boundary was crossed, which AI operator failed, or which constraint was violated.

This registry outlines the core error codes thrown by the Carotene CLI.

1. Compiler & Syntax Errors (E1000s)

These errors occur immediately when you save a file. They indicate that your .carrot blueprint is structurally invalid.

E1001: TypeMismatch

Cause: You attempted to assign a value to a variable or field that does not match its strictly defined type in the model.

Fix: Ensure the assignment matches the schema. Remember that optional fields (String?) must be handled safely.

// Error: Cannot assign Int to String
user.email = 12345

E1002: UnresolvedReference

Cause: You referenced a model, store, or integration that has not been defined in your workspace or current namespace.

Fix: Check your spelling or ensure the target domain is properly exported.

E1003: OrphanedOperator

Cause: You placed a Generative Operator (@(...)) outside of a valid execution block (like a function or test). The AI cannot generate code without a surrounding execution context.

2. Zero-Trust & Boundary Errors (E2000s)

These are static analysis errors. The compiler catches them before passing your code to the AI or the Sandbox.

E2001: VerbViolation

Cause: You (or the AI) attempted to perform a database mutation or network call that was not explicitly authorized by your Zero-Trust verbs (reads, updates, creates, deletes, calls).

Fix: Add the required verb to the top of your function block.

// Fix: Add `updates store.Order` to the function
function Refund(orderId: store.Order.id) {
  updates store.Order // <-- Missing this caused E2001
  implements {
    targetOrder = store.Order.find(orderId)
    triggers targetOrder.status.Refunded
  }
}

E2002: IllegalStateTransition

Cause: You used the triggers keyword to push a model into a state that is not explicitly allowed by its flow definition.

Fix: Update your flow block to permit the transition, or correct the business logic.

3. Generative AI Errors (E3000s)

These errors occur during carrot dev or carrot build when the LLM is attempting to resolve your @(...) operators.

E3001: GenerativeResolutionFailed

Cause: The Vapor Sandbox executed the AI's generated code, but it failed your asserts statements. The Sandbox fed the error back to the AI, but after reaching the max_retries limit (default: 5), the AI could not produce passing code.

Fix: Your prompt is likely too ambiguous, or your test assertions are mathematically impossible. Rewrite the @(...) text to be more explicit.

E3002: ContextExhausted

Cause: The Context Matrix required to generate your operator exceeds the token limit of your configured AI provider. This usually happens if you give a single function access to 50 different database tables.

Fix: Break your function down into smaller, single-responsibility functions.

4. Sandbox & Testing Errors (E4000s)

These errors are thrown by the Deterministic Sandbox when running your test blocks.

E4001: NetworkGuillotineTriggered

Cause: The function you are testing attempted to make an outbound HTTP request (via an integration), but you did not intercept it with a mock keyword in your test block. The Sandbox physically severed the connection.

Fix: Add mock integration.[Name] -> [Value] to your test block.

E4002: AssertionFailed

Cause: The executed code did not match your explicit asserts statement.

Output: The CLI will provide a deterministic diff showing exactly what was expected versus what actually happened in the sandbox memory.

[E4002] Assertion Failed at line 42:
  Expected: 95.0
  Received: 100.0

E4003: SandboxTimeout

Cause: The generated code caused an infinite loop or took longer than the configured timeout limit (default 5000ms).

Fix: If you are running a heavy query, increase the timeout in the config {} block. Otherwise, prompt the AI to avoid unbounded loops.

5. Runtime Security Errors (HTTP Codes)

When your Carotene app is compiled and running in production, it automatically maps structural security rules to standard HTTP errors.

• 400 Bad Request: Thrown automatically if an incoming JSON payload fails to strictly match the defined modelschema, or if you explicitly use the throws keyword.
• 401 Unauthorized: Thrown automatically if an endpoint is called but the session object is missing or invalid.
• 403 Forbidden: Thrown automatically if a requires statement (RBAC) evaluates to false (e.g., requires session.role == Admin).