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¶

Search by Error Code: If you see an error code like E001, look it up directly in the table below
Browse by Category: Errors are categorized into compile-time errors, runtime errors, tool errors, etc.
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: "Intelligent Assistant",       // Required
    prompt: "Help users solve problems", // Required
    model: "gpt-4"          // Optional
}

E004 - Duplicate Declaration¶

Error Message:

Error E004: Duplicate declaration 'Analyst'
  --> main.nexa:25:1
   |
25 | agent Analyst {
   | ^^^^^^^^^^^^^ 'Analyst' already declared at line 10

Cause: - Multiple Agents, Tools, or Protocols with the same name defined in the same scope

Solution:

// ❌ Wrong: Duplicate declaration
agent Analyst { role: "Analyst", prompt: "..." }
agent Analyst { role: "Data Analyst", prompt: "..." }  // Duplicate!

// ✅ Correct: Use different names
agent DataAnalyst { role: "Data Analyst", prompt: "..." }
agent MarketAnalyst { role: "Market Analyst", prompt: "..." }

E005 - Invalid Model Identifier¶

Error Message:

Error E005: Invalid model identifier 'gpt5'
  --> main.nexa:12:12
   |
12 |     model: "gpt5",
   |            ^^^^^ 'gpt5' is not a valid model

Cause: - Model name typo - Using an unsupported model

Solution:

// ❌ Wrong: Invalid model name
agent MyAgent {
    role: "Assistant",
    prompt: "...",
    model: "gpt5"  // Doesn't exist
}

// ✅ Correct: Use valid model
agent MyAgent {
    role: "Assistant",
    prompt: "...",
    model: "gpt-4"  // Or gpt-4o, claude-3-sonnet, etc.
}

Supported Models List: - OpenAI: gpt-4, gpt-4-turbo, gpt-4o, gpt-3.5-turbo - Anthropic: claude-3-opus, claude-3-sonnet, claude-3-haiku - Local: llama-2, mistral, etc. (requires local model configuration)

E006 - Protocol Not Found¶

Error Message:

Error E006: Protocol 'ReportFormat' not found
  --> main.nexa:18:30
   |
18 | agent Reporter implements ReportFormat {
   |                              ^^^^^^^^^^^^^ not declared

Cause: - Protocol referenced by implements is not declared - Protocol name typo

Solution:

// ❌ Wrong: Referencing undeclared Protocol
agent Reporter implements ReportFormat {
    role: "Reporter",
    prompt: "..."
}

// ✅ Correct: Declare Protocol first
protocol ReportFormat {
    title: "string",
    content: "string"
}

agent Reporter implements ReportFormat {
    role: "Reporter",
    prompt: "..."
}

E007 - Tool Not Found¶

Error Message:

Error E007: Tool 'web_search' not found
  --> main.nexa:20:20
   |
20 | agent Searcher uses web_search {
   |                    ^^^^^^^^^^ not declared

Cause: - Tool referenced by uses is not declared - Tool name typo - Standard library not imported

Solution:

// ❌ Wrong: Referencing undeclared Tool
agent Searcher uses web_search {
    role: "Search Assistant",
    prompt: "..."
}

// ✅ Correct Method 1: Declare Tool
tool web_search {
    description: "Search the web",
    parameters: {"query": "string"}
}

agent Searcher uses web_search {
    role: "Search Assistant",
    prompt: "..."
}

// ✅ Correct Method 2: Use Standard Library
agent Searcher uses std.web_search {
    role: "Search Assistant",
    prompt: "..."
}

E008 - Syntax Error¶

Error Message:

Error E008: Syntax error
  --> main.nexa:30:1
   |
30 | agent MyAgent
   | ^^^^^^^^^^^^^ expected '{' after agent name

Cause: - Missing necessary syntax elements (brackets, commas, etc.) - Keyword typo - Indentation or format issues

Solution:

// ❌ Wrong: Missing braces
agent MyAgent
    role: "Assistant"

// ✅ Correct: Complete syntax
agent MyAgent {
    role: "Assistant",
    prompt: "..."
}

E009 - Invalid Regex¶

Error Message:

Error E009: Invalid regex pattern
  --> main.nexa:15:20
   |
15 |     fast_match r"[a-z" against input
   |                 ^^^^^ unterminated character class

Cause: - Regex syntax error used in fast_match

Solution:

// ❌ Wrong: Incomplete regex
semantic_if "Match email" fast_match r"[a-z+@" against input {
    ...
}

// ✅ Correct: Complete regex
semantic_if "Match email" fast_match r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}" against input {
    ...
}

E010 - Invalid Property Value¶

Error Message:

Error E010: Invalid property value for 'memory'
  --> main.nexa:12:14
   |
12 |     memory: "permanent",
   |              ^^^^^^^^^^ expected 'short', 'long', or 'session'

Cause: - Property value not in allowed options range

Solution:

// ❌ Wrong: Invalid memory value
agent MyAgent {
    role: "Assistant",
    prompt: "...",
    memory: "permanent"  // Invalid
}

// ✅ Correct: Use valid value
agent MyAgent {
    role: "Assistant",
    prompt: "...",
    memory: "long"  // Valid values: short, session, long
}

2. Runtime Errors (E1xx)¶

Runtime errors occur during program execution, usually related to external resources or configuration.

E101 - Agent Execution Timeout¶

Error Message:

Runtime Error E101: Agent execution timeout
  Agent: 'Analyst'
  Timeout: 60 seconds

Cause: - Agent execution time exceeded limit - Slow model response - Network connection issues

Solution:

// Solution 1: Increase timeout
@timeout(seconds=120)
agent Analyst {
    role: "Analyst",
    prompt: "..."
}

// Solution 2: Use faster model
agent Analyst {
    role: "Analyst",
    prompt: "...",
    model: "gpt-3.5-turbo"  // Faster than gpt-4
}

// Solution 3: Add fallback
agent Analyst {
    role: "Analyst",
    prompt: "...",
    fallback: "gpt-3.5-turbo"
}

E102 - Model Call Failed¶

Error Message:

Runtime Error E102: Model API call failed
  Model: 'gpt-4'
  Status: 429 - Rate limit exceeded
  Message: You have exceeded your API rate limit

Cause: - API key invalid or expired - API quota exhausted - Network connection issues - Model service unavailable

Solution:

# Check API key
nexa doctor

# Update key configuration
nexa config set api.openai_key "sk-xxx"

// Add fallback model
agent MyAgent {
    role: "Assistant",
    prompt: "...",
    model: "gpt-4",
    fallback: "gpt-3.5-turbo"  // Downgrade when main model fails
}

E103 - Protocol Validation Failed¶

Error Message:

Runtime Error E103: Protocol validation failed
  Agent: 'Reporter'
  Protocol: 'Report'
  Missing fields: ['summary']
  Invalid fields: {'score': 'expected number, got string'}

Cause: - Agent output doesn't match Protocol-defined format - Field type mismatch

Solution:

// Check Protocol definition
protocol Report {
    title: "string",
    summary: "string",   // Ensure required fields
    score: "number"      // Ensure correct type
}

// Optimize Agent prompt to ensure output format
agent Reporter implements Report {
    role: "Reporter",
    prompt: """
    Generate structured report, must include the following fields:
    - title: Report title (string)
    - summary: Report summary (string)
    - score: Rating (number, 0-100)
    """
}

E104 - Tool Execution Error¶

Error Message:

Runtime Error E104: Tool execution error
  Tool: 'web_search'
  Error: Connection timeout

Cause: - External service depended on by tool is unavailable - Network connection issues - Tool parameter errors

Solution:

// Add error handling
try {
    result = web_search.run(query);
} catch (error) {
    print("Search failed: " + error);
    result = "Unable to perform search";
}

E105 - Authentication Failed¶

Error Message:

Runtime Error E105: Authentication failed
  Service: OpenAI API
  Reason: Invalid API key

Cause: - API key invalid or expired - Key not properly configured

Solution:

# Check environment configuration
nexa doctor

# Configure key
# Method 1: Environment variable
export OPENAI_API_KEY="sk-xxx"

# Method 2: secrets.nxs file
echo 'OPENAI_API_KEY: "sk-xxx"' > secrets.nxs

# Method 3: Configuration command
nexa config set api.openai_key "sk-xxx"

E106 - Loop Exceeded Maximum Iterations¶

Error Message:

Runtime Error E106: Loop exceeded maximum iterations
  Loop: line 45
  Max iterations: 10

Cause: - loop until condition never satisfied - Logic error causing infinite loop

Solution:

// ❌ Wrong: Potential infinite loop
loop {
    draft = Editor.run(feedback);
    feedback = Critic.run(draft);
} until ("Perfect")  // Condition too strict, may never be satisfied

// ✅ Correct: Add safe exit
max_iterations = 5;
count = 0;
loop {
    draft = Editor.run(feedback);
    feedback = Critic.run(draft);
    count = count + 1;
    if count >= max_iterations {
        print("Reached maximum iterations");
        break;
    }
} until ("Article quality acceptable")

E107 - Intent Match Failed¶

Error Message:

Runtime Error E107: No intent matched
  Input: "Book me a flight ticket"
  Available intents: ["Check weather", "Set reminder", "Play music"]

Cause: - match intent didn't match any branch - Missing default branch _

Solution:

// ❌ Wrong: Missing default branch
match user_input {
    intent("Check weather") => WeatherBot.run(user_input),
    intent("Set reminder") => ReminderBot.run(user_input)
    // Error if neither matches
}

// ✅ Correct: Add default branch
match user_input {
    intent("Check weather") => WeatherBot.run(user_input),
    intent("Set reminder") => ReminderBot.run(user_input),
    _ => DefaultBot.run(user_input)  // Fallback handling
}

3. Configuration Errors (E2xx)¶

Configuration errors relate to project configuration and environment settings.

E201 - Configuration File Not Found¶

Error Message:

Error E201: Configuration file not found
  Path: ./nexa.yaml

Cause: - Configuration file doesn't exist - Configuration file path error

Solution:

# Initialize configuration file
nexa config init

# Or specify configuration file path
nexa run main.nexa --config ./config/nexa.yaml

E202 - Invalid Configuration Value¶

Error Message:

Error E202: Invalid configuration value
  Key: model.temperature
  Value: "hot"
  Expected: number between 0 and 2

Cause: - Configuration value type or range error

Solution:

# ❌ Wrong
model:
  temperature: "hot"

# ✅ Correct
model:
  temperature: 0.7  # 0.0 - 2.0

E203 - Secrets File Error¶

Error Message:

Error E203: Secrets file error
  File: secrets.nxs
  Reason: File format invalid

Cause: - secrets.nxs file format error - Secrets file permission issues

Solution:

# Check file format
cat secrets.nxs

# Ensure correct format
echo 'OPENAI_API_KEY: "sk-xxx"' > secrets.nxs
echo 'ANTHROPIC_API_KEY: "sk-ant-xxx"' >> secrets.nxs

# Set correct file permissions
chmod 600 secrets.nxs

4. Tool and MCP Errors (E3xx)¶

E301 - MCP Server Connection Failed¶

Error Message:

Error E301: MCP server connection failed
  Server: web-search-mcp
  Reason: Connection refused

Cause: - MCP server not started or unreachable - Network connection issues

Solution:

# Check MCP server status
nexa mcp test web-search

# Re-add MCP server
nexa mcp remove web-search
nexa mcp add web-search "github.com/nexa-ai/web-search-mcp"

E302 - Tool Parameter Validation Failed¶

Error Message:

Error E302: Tool parameter validation failed
  Tool: 'web_search'
  Parameter: 'query'
  Error: Required parameter missing

Cause: - Missing required parameters when calling tool - Parameter type mismatch

Solution:

// ❌ Wrong: Missing required parameter
result = web_search.run();

// ✅ Correct: Provide required parameter
result = web_search.run(query: "Nexa language");

E303 - Standard Library Tool Not Found¶

Error Message:

Error E303: Standard library tool not found
  Tool: 'std.json.parse'
  Reason: Tool not registered in namespace

Cause: - Tool namespace spelling error - Using non-existent tool

Solution:

// ❌ Wrong: Namespace spelling error
result = std.json.parse(text);  // Correct

// ❌ Wrong: Using old naming convention
result = std.fs.read(path);     // New version: std.fs.file_read

// ✅ Correct: Use full tool name
result = std.json.json_parse(text);
result = std.fs.file_read(path);

4.1 AVM Runtime Errors (E4xx) - v1.0-alpha¶

E401 - AVM Bytecode Execution Failed¶

Error Message:

Error E401: AVM bytecode execution failed
  Opcode: FireForget
  Reason: Agent list cannot be empty

Cause: - DAG operator parameter configuration error - Invalid Agent ID

Solution:

// ❌ Wrong: Empty Agent list
notification || [];  // Cannot use empty list

// ✅ Correct: Specify at least one Agent
notification || [EmailBot];

E402 - WASM Sandbox Permission Denied¶

Error Message:

Error E402: WASM sandbox permission denied
  Tool: 'shell_exec'
  Required: Elevated
  Current: Standard

Cause: - Tool requires higher permission level - WASM resource limit exceeded

Solution:

// Declare required permissions in agent definition
agent SystemAgent uses std.shell {
    role: "System Management Assistant",
    prompt: "...",
    // Need to elevate permissions in runtime configuration
}

E403 - Vector Memory Page Overflow¶

Error Message:

Error E403: Vector memory page overflow
  Active pages: 256
  Max allowed: 128

Cause: - Conversation history too long exceeds memory limit - Page compression not enabled

Solution:

// Use memory property to control memory length
agent LongConversationBot {
    role: "Long Conversation Assistant",
    memory: "compressed",  // Enable compression mode
    // Or limit memory turns
}

E404 - Consensus Operation Timeout¶

Error Message:

Error E404: Consensus operation timeout
  Agents: [ExpertA, ExpertB, ExpertC]
  Waited: 60s
  Completed: 2/3

Cause: - Consensus operator && wait timeout - Some Agents not responding

Solution:

// Use timeout decorator to control wait time
@timeout(seconds=120)
agent ConsensusJudge {
    role: "Consensus Judge",
    prompt: "..."
}

// Or use fire-forget instead
decision = question || [ExpertA, ExpertB, ExpertC];

5. Warning Messages (W0xx)¶

Warnings don't prevent program execution, but it's recommended to fix them to avoid potential issues.

W001 - Unused Declaration¶

Warning Message:

Warning W001: Unused agent 'TempAgent'
  --> main.nexa:15:1

Solution: - Delete unused declaration, or - Use the declaration in code

W002 - Performance Warning¶

Warning Message:

Warning W002: Potential performance issue
  Agent 'SlowAgent' has high temperature (1.5) and long prompt
  This may cause inconsistent or slow responses

Solution: - Lower temperature value - Simplify prompt - Use faster model

W003 - Deprecation Warning¶

Warning Message:

Warning W003: Deprecated feature
  'semantic_match' is deprecated, use 'semantic_if' instead

Solution: - Update code to use new syntax

6. Error Handling Best Practices¶

6.1 Use try/catch¶

flow main(input: string) {
    try {
        result = RiskyAgent.run(input);
        print(result);
    } catch (error) {
        print("Execution failed: " + error);
        result = FallbackAgent.run(input);
    }
}

6.2 Add Fallback¶

agent MyAgent {
    role: "Assistant",
    prompt: "...",
    model: "gpt-4",
    fallback: "gpt-3.5-turbo"  // Auto downgrade when main model fails
}

6.3 Set Reasonable Timeout¶

@timeout(seconds=30)
agent QuickAgent {
    role: "Quick Response Assistant",
    prompt: "Answer user questions concisely"
}

6.4 Prevent Infinite Loops¶

max_iterations = 5;
count = 0;
loop {
    // ... loop body
    count = count + 1;
    if count >= max_iterations {
        break;
    }
} until ("Condition satisfied")

快来问问agent吧！

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

Nexa Error Index¶

📖 How to Use This Index¶

1. Compile-Time Errors (E0xx)¶

E001 - Undeclared Identifier¶

E002 - Type Mismatch¶

E003 - Missing Required Property¶

E004 - Duplicate Declaration¶

E005 - Invalid Model Identifier¶

E006 - Protocol Not Found¶

E007 - Tool Not Found¶

E008 - Syntax Error¶

E009 - Invalid Regex¶

E010 - Invalid Property Value¶

2. Runtime Errors (E1xx)¶

E101 - Agent Execution Timeout¶

E102 - Model Call Failed¶

E103 - Protocol Validation Failed¶

E104 - Tool Execution Error¶

E105 - Authentication Failed¶

E106 - Loop Exceeded Maximum Iterations¶

E107 - Intent Match Failed¶

3. Configuration Errors (E2xx)¶

E201 - Configuration File Not Found¶

E202 - Invalid Configuration Value¶

E203 - Secrets File Error¶

4. Tool and MCP Errors (E3xx)¶

E301 - MCP Server Connection Failed¶

E302 - Tool Parameter Validation Failed¶

E303 - Standard Library Tool Not Found¶

4.1 AVM Runtime Errors (E4xx) - v1.0-alpha¶

E401 - AVM Bytecode Execution Failed¶

E402 - WASM Sandbox Permission Denied¶

E403 - Vector Memory Page Overflow¶

E404 - Consensus Operation Timeout¶

5. Warning Messages (W0xx)¶

W001 - Unused Declaration¶

W002 - Performance Warning¶

W003 - Deprecation Warning¶

6. Error Handling Best Practices¶

6.1 Use try/catch¶

6.2 Add Fallback¶

6.3 Set Reasonable Timeout¶

6.4 Prevent Infinite Loops¶

🔗 Related Resources¶