Skip to content

Nexa Error Index

This index contains all error codes, cause analysis, and solutions that may be generated by the Nexa compiler and runtime.

📖 How to Use This Index

  1. Search by Error Code: If you see an error code like E001, look it up directly in the table below
  2. Browse by Category: Errors are categorized into compile-time errors, runtime errors, contract errors, type errors, etc.
  3. View Solutions: Each error comes with detailed cause analysis and resolution suggestions

1. Compile-Time Errors (E0xx)

Compile-time errors are detected during the code compilation phase, indicating syntax or semantic issues in the code.

E001 - Undeclared Identifier

Error Message: 

Error E001: Undeclared identifier 'X'
  --> main.nexa:15:5
   |
15 |     result = UnknownAgent.run(input);
   |              ^^^^^^^^^^^^^ 'UnknownAgent' not found

Cause: - Referenced an undefined Agent, Tool, or Protocol - Identifier typo - Forgot to import necessary modules

Solution:

// ❌ Wrong: Undeclared
result = WeatherBot.run(input);

// ✅ Correct: Declare before use
agent WeatherBot {
    role: "Weather Assistant",
    prompt: "Answer weather-related questions"
}

result = WeatherBot.run(input);

E002 - Type Mismatch

Error Message: 

Error E002: Type mismatch
  --> main.nexa:23:20
   |
23 | protocol Report { score: "number" }
   |                    ^^^^^ expected 'number', found 'string'

Cause: - Protocol field type doesn't match actual output - Type annotation format error

Solution:

// ❌ Wrong: Type annotation format error
protocol Report {
    score: number    // Type not in quotes
}

// ✅ Correct: Type annotation needs quotes
protocol Report {
    score: "number"  // Correct format
}

E003 - Missing Required Property

Error Message: 

Error E003: Missing required property 'role'
  --> main.nexa:10:1
   |
10 | agent MyAgent {
   | ^^^^^^^^^^^^^ 'role' property is required

Cause: - Agent missing required role property - Agent missing required prompt property

Solution:

// ❌ Wrong: Missing required property
agent MyAgent {
    model: "gpt-4"
}

// ✅ Correct: Add required properties
agent MyAgent {
    role: "Assistant",
    prompt: "Help users solve problems",
    model: "gpt-4"
}

E004 - Syntax Error

Error Message: 

Error E004: Syntax error
  --> main.nexa:5:1
   |
5 | agent { }
   | ^^^^^^^^ Expected IDENTIFIER after 'agent'

Cause: - Missing identifier name - Incomplete syntax structure - Invalid syntax construct

Solution: Check that the syntax conforms to the Nexa specification. Refer to the Language Reference Manual.

E005 - Duplicate Declaration

Error Message: 

Error E005: Duplicate declaration 'MyAgent'
  --> main.nexa:20:1
   |
20 | agent MyAgent { ... }
   | ^^^^^^^^^^^^^ 'MyAgent' already declared

Cause: - Same-named Agent, Tool, or Protocol declared multiple times in the same file

Solution: Use different names or remove the duplicate declaration.

2. Runtime Errors (E1xx)

Runtime errors occur during program execution.

E101 - Agent Execution Failed

Error Message: 

Error E101: Agent execution failed
  Agent 'Analyst' failed after 3 retries

Cause: - LLM API call failed (network error, invalid API Key) - Model output format doesn't match expectations - Execution timeout

Solution:

// Set fallback model
agent MyAgent {
    model: "gpt-4",
    fallback: "gpt-3.5-turbo",
    timeout: 60,
    retry: 5
}

E102 - Tool Execution Failed

Error Message: 

Error E102: Tool execution failed
  Tool 'web_search' returned error: HTTP timeout

Cause: - External service unavailable - Incorrect tool parameters - Execution timeout

Solution: Check tool parameters, network connection, and timeout settings.

E103 - Pipeline Execution Failed

Error Message: 

Error E103: Pipeline execution failed
  Pipeline stage 'Reviewer' failed

Cause: - An Agent in the pipeline failed to execute - Data format mismatch between stages

Solution: Check each Agent's independent execution in the pipeline, ensure data format compatibility.

E104 - Intent Routing Failed

Error Message: 

Error E104: Intent routing failed
  No matching intent for input: "..."

Cause: - Intent matcher cannot recognize user input - All intent branches unmatched

Solution: Add a _ wildcard branch as default handling.

match user_input {
    intent("Check weather") => WeatherBot.run(user_input),
    intent("Check news") => NewsBot.run(user_input),
    _ => ChatBot.run(user_input)    // Default branch
}

3. Contract Errors (E2xx) — v1.2.0+

E201 - ContractViolation (requires Precondition Violation)

Error Message: 

ContractViolation(requires:deterministic, message="amount must be positive")
  --> transfer.nexa:5

Cause: - requires deterministic condition not satisfied (e.g., amount > 0 but negative value passed) - requires semantic condition not satisfied (e.g., "sender has sufficient balance" but balance insufficient)

Solution:

// Deterministic contract: ensure input parameters satisfy conditions
flow transfer(amount: int) -> Result
    requires: amount > 0
{
    if (amount <= 0) {
        return Result::Err("Invalid amount");
    }
    // ...
}

// Semantic contract: ensure input satisfies semantic requirements
flow review(code: string) -> Report
    requires: "input contains valid source code"
{
    // ...
}

E202 - ContractViolation (ensures Postcondition Violation)

Error Message: 

ContractViolation(ensures:semantic, message="result must include actionable feedback")
  --> review.nexa:8

Cause: - ensures deterministic condition not satisfied (e.g., result.success == true but returned failure) - ensures semantic condition not satisfied (e.g., "result includes actionable feedback" but output has no suggestions)

Solution: Ensure function return values satisfy postconditions, or adjust conditions to be more reasonable.

E203 - ContractViolation (invariant Violation)

Error Message: 

ContractViolation(invariant:deterministic, message="state must be idle or running")

Cause: - invariant condition violated during object lifecycle

Solution: Ensure object state always satisfies invariant constraints.

4. Type Errors (E3xx) — v1.3.1+

E301 - TypeViolation (strict Mode Type Violation)

Error Message: 

TypeViolation: Expected Int, got String
  --> main.nexa:10
   |
10 | let x: Int = "hello"
   |               ^^^^^^^ Type mismatch

Cause: - Under NEXA_TYPE_MODE=strict mode, type mismatch causes runtime error

Solution:

// Ensure type matches
let x: Int = 42           // ✅ Correct
let y: String = "hello"   // ✅ Correct

// Or switch to warn mode
// Set NEXA_TYPE_MODE=warn

E302 - TypeWarning (warn Mode Type Warning)

Error Message: 

TypeWarning: Expected Int, got String (mode: warn)
  --> main.nexa:10

Cause: - Under NEXA_TYPE_MODE=warn mode, type mismatch only emits a warning; program continues execution

Solution: Fix type annotations or values to ensure type consistency.

E303 - Protocol Type Validation Failed

Error Message: 

Error E303: Protocol validation failed
  Protocol 'ReviewResult' field 'score' expected int, got string

Cause: - Agent output doesn't match protocol-defined field types - LLM-returned JSON format doesn't match protocol

Solution:

// Use implements to constrain Agent output
agent Reviewer implements ReviewResult {
    prompt: "Review the code. Return JSON with score (int) and summary (string)."
}

5. Database Errors (E4xx) — v1.3.5+

E401 - DatabaseError (Connection Failed)

Error Message: 

DatabaseError: Failed to connect to sqlite://data.db

Cause: - Database file path doesn't exist - SQLite file permission issues - PostgreSQL connection parameter errors

Solution: Check database path, permissions, and connection parameters.

E402 - DatabaseError (Query Failed)

Error Message: 

DatabaseError: Query failed: SELECT * FROM nonexistent_table

Cause: - SQL syntax error - Table or column doesn't exist - Parameter binding error

Solution: Check SQL statement and table structure.

E403 - DatabaseError (Transaction Failed)

Error Message: 

DatabaseError: Transaction failed, rolled back

Cause: - An operation in the transaction failed, causing rollback

Solution: Check each operation in the transaction, ensure data consistency.

6. Auth Errors (E5xx) — v1.3.6+

E501 - AuthError (Authentication Failed)

Error Message: 

AuthError: Invalid API key format

Cause: - API Key format incorrect (should be nexa-ak-{32hex} format) - API Key expired or revoked

Solution: Use std.auth.api_key_generate to generate a correctly formatted API Key.

E502 - AuthError (JWT Error)

Error Message: 

AuthError: JWT signature verification failed

Cause: - JWT signature verification failed - JWT expired - JWT format incorrect

Solution: Check JWT key configuration and token validity period.

E503 - AuthError (CSRF Validation Failed)

Error Message: 

AuthError: CSRF token validation failed

Cause: - CSRF Token mismatch - Token expired

Solution: Ensure the form contains the correct CSRF Token.

E504 - AuthError (OAuth Flow Error)

Error Message: 

AuthError: OAuth PKCE flow failed

Cause: - OAuth Provider configuration error - PKCE code_verifier mismatch - redirect_uri mismatch

Solution: Check OAuth Provider configuration (client_id, client_secret, redirect_uri).

7. KV Store Errors (E6xx) — v1.3.6+

E601 - KVError (Operation Failed)

Error Message: 

KVError: Key 'user_prefs' not found

Cause: - Key doesn't exist - KV Store not opened - TTL expired

Solution: Use ?? operator to provide default values, or check key existence first.

value = kv.get("user_prefs") ?? "default"
if (kv.has("user_prefs")) {
    value = kv.get("user_prefs")
}

E602 - KVError (Serialization Failed)

Error Message: 

KVError: Failed to deserialize value for key 'config'

Cause: - Stored data type doesn't match read type - Data corruption

Solution: Use type-safe read methods (kv_get_int, kv_get_str, kv_get_json).

8. Concurrency Errors (E7xx) — v1.3.6+

E701 - ConcurrencyError (Task Cancelled)

Error Message: 

ConcurrencyError: Task 'my_task' was cancelled

Cause: - Task actively cancelled by cancel_task - Task automatically cancelled due to timeout

Solution: Check task logic, ensure cancellation is expected behavior.

E702 - ConcurrencyError (Channel Closed)

Error Message: 

ConcurrencyError: Channel is closed

Cause: - Sending message to a closed channel - Receiving message from a closed channel

Solution: Check channel status before send/receive, or use try_recv to avoid blocking.

E703 - ConcurrencyError (race All Failed)

Error Message: 

ConcurrencyError: All tasks in race failed

Cause: - All tasks in race failed

Solution: Ensure at least one task can complete successfully.

9. Template Errors (E8xx) — v1.3.6+

E801 - TemplateError (Compilation Failed)

Error Message: 

TemplateError: Failed to compile template: unclosed {{#for}} block

Cause: - Template syntax error (unclosed block) - Filter name doesn't exist

Solution: Check template syntax, ensure all blocks are properly closed.

E802 - TemplateError (Rendering Failed)

Error Message: 

TemplateError: Failed to render template: variable 'name' not found

Cause: - Variable referenced in template doesn't exist in data - Data format mismatch

Solution: Use | default(val) filter to provide default values.

template"""Hello {{name | default("Guest")}}!"""

10. Pattern Matching Errors (E9xx) — v1.3.x+

E901 - PatternMatchError (No Matching Branch)

Error Message: 

PatternMatchError: No matching pattern for value

Cause: - No branch in match expression matches the current value - Missing _ wildcard branch

Solution: Add a _ wildcard branch as default match.

match result {
    Option::Some(v) => v
    Option::None => "no response"
    _ => "unknown"    // Wildcard fallback
}

E902 - PatternMatchError (Destructuring Failed)

Error Message: 

PatternMatchError: Destructuring failed for pattern (a, b)

Cause: - Destructuring pattern doesn't match data structure (e.g., using tuple pattern on non-tuple value)

Solution: Ensure destructuring pattern matches data structure type.

11. ADT Errors (EAx) — v1.3.x+

EA01 - ADTError (Struct Operation Failed)

Error Message: 

ADTError: Struct 'Point' not found

Cause: - Referenced unregistered struct - Field access doesn't exist

Solution: Ensure struct is declared and field names are correct.

EA02 - ADTError (Enum Operation Failed)

Error Message: 

ADTError: Variant 'Some' not found in enum 'Option'

Cause: - Referenced unregistered enum variant - Variant name typo

Solution: Ensure enum and variant names are correct.

EA03 - ADTError (Trait Method Call Failed)

Error Message: 

ADTError: No impl found for trait 'Printable' on type 'Point'

Cause: - Type doesn't implement the trait - Missing impl declaration

Solution: Add an impl declaration.

impl Printable for Point {
    fn format() -> String { ... }
}

12. Job System Errors (EBx) — v1.3.3+

EB01 - JobError (Job Execution Failed)

Error Message: 

JobError: Job 'SendEmail' failed after 2 retries

Cause: - Job logic execution failed - Retry count exhausted

Solution: Check on_failure handling logic, increase retry count.

EB02 - JobError (Job Timeout)

Error Message: 

JobError: Job 'AnalyzeDoc' timed out after 120s

Cause: - Job execution time exceeded timeout setting

Solution: Increase timeout value or optimize job logic.

EB03 - JobError (Dead Letter Job)

Error Message: 

JobError: Job 'SendEmail' is in dead letter queue

Cause: - All job retries failed, entered dead letter queue

Solution: Use nexa jobs retry <job_id> to retry dead letter jobs.

13. HTTP Server Errors (ECx) — v1.3.4+

EC01 - HTTPError (Route Not Found)

Error Message: 

HTTPError: No route found for GET /unknown

Cause: - Request path not defined in server DSL

Solution: Add the corresponding route in the server declaration.

EC02 - ContractViolation (HTTP Contract Violation)

Error Message: 

ContractViolation(requires) → HTTP 401 Unauthorized
ContractViolation(ensures) → HTTP 403 Forbidden

Cause: - HTTP request violated route's requires precondition → 401 - HTTP response violated ensures postcondition → 403

Solution: Ensure requests satisfy preconditions and responses satisfy postconditions.

📊 Error Code Quick Reference Table

Error Code Category Description
E001 Compile-time Undeclared identifier
E002 Compile-time Type mismatch
E003 Compile-time Missing required property
E004 Compile-time Syntax error
E005 Compile-time Duplicate declaration
E101 Runtime Agent execution failed
E102 Runtime Tool execution failed
E103 Runtime Pipeline execution failed
E104 Runtime Intent routing failed
E201 Contract requires precondition violation
E202 Contract ensures postcondition violation
E203 Contract invariant violation
E301 Type TypeViolation (strict)
E302 Type TypeWarning (warn)
E303 Type Protocol type validation failed
E401 Database Connection failed
E402 Database Query failed
E403 Database Transaction failed
E501 Auth Authentication failed
E502 Auth JWT error
E503 Auth CSRF validation failed
E504 Auth OAuth flow error
E601 KV Operation failed
E602 KV Serialization failed
E701 Concurrency Task cancelled
E702 Concurrency Channel closed
E703 Concurrency race all failed
E801 Template Compilation failed
E802 Template Rendering failed
E901 Pattern Matching No matching branch
E902 Pattern Matching Destructuring failed
EA01 ADT Struct operation failed
EA02 ADT Enum operation failed
EA03 ADT Trait method call failed
EB01 Job Job execution failed
EB02 Job Job timeout
EB03 Job Dead letter job
EC01 HTTP Route not found
EC02 HTTP Contract violation
快来问问agent吧！

Nexa Agent

Nexa 文档助手

我是Nexa文档AI助手，可以问我有关文档的一切！

由AI Hub提供支持