Execution Errors
run() does not reject for a failing script. It resolves with success: false and an error that has a name, a message and a code. The message says what happened; the code says which stage reported it. See Error Codes for the complete list.
VALIDATION_ERROR
Cause: Code failed AST validation: a blocked construct was used. Also returned for a script of more than 5,242,880 characters, or one that is not a string. Example:- Review the AgentScript language definition
- Remove blocked constructs from your code
- Check the validation issues for specific lines
Errors of the running script
A script that fails while it runs has the codeDOUBLE_VM_EXECUTION_ERROR (or VM_EXECUTION_ERROR with doubleVm: { enabled: false }), whatever the reason. Tell the reasons apart by the message.
Timeout
Message: starts withScript execution timed out, for example Script execution timed out after 5000ms
Cause: Execution exceeded the configured timeout.
Solutions:
- Optimize slow tool calls
- Reduce iteration count
- Increase timeout (if appropriate)
adapter: 'worker_threads', a script that is still running five seconds after its timeout is terminated with its worker, and the error is WorkerTimeoutError with the code EXECUTION_ERROR.
Tool call limit
Message:Maximum tool call limit exceeded (50). This limit prevents runaway script execution.
Cause: Script made too many tool calls.
Solutions:
- Batch operations in tools instead of individual calls
- Increase maxToolCalls limit
- Review script logic for unnecessary calls
Iteration limit
Message: starts withMaximum iteration limit exceeded
Cause: Loop iterations exceeded the limit.
Solutions:
- Use pagination or limits in data fetching
- Process data in chunks
- Increase maxIterations (carefully)
A tool failed
Cause: A tool handler threw an error, and the script did not catch it. The message is the handler’s. Solutions:- Check tool inputs are valid
- Throw errors with meaningful messages from tool handlers
- Let the script handle the failure:
try/catch, orcallTool(name, args, { throwOnError: false }), which resolves to{ success: false, error }instead of throwing
MEMORY_LIMIT_EXCEEDED
Cause: Script used more memory thanmemoryLimit allows, as the enclave counts it. The default limit is 1 MB.
Example:
error.data holds usedBytes and limitBytes.
Solutions:
- Process large data in chunks
- Pass large strings between tools by reference with the Reference Sidecar
- Increase memory limit
38.15MB used for a short script, or gigabytes) points at an array’s length, not at its contents: an array is counted by its slots, 8 bytes each, whether they hold anything or not. The usual causes are an array used as a sparse map (seen[userId] = true), an assignment to length, Array(n) with a large n, and an array method called on an object with a large length. Use an object or a Map for keys that are not small consecutive indexes.
A returned value that is larger than the memory limit allows fails with SERIALIZATION_LIMIT_EXCEEDED.
SECURITY_VIOLATION
Cause: The script contains a dynamic import (import() or import.meta), which is refused before the script runs, also with validate: false. At STRICT and SECURE the code is also returned when the runtime recorded a blocked operation during the run.
Solution: Remove the construct. A script reaches the outside through tools only.
SCORING_BLOCKED
Cause: The AI Scoring Gate gave the script a score at or aboveblockThreshold, or it could not score the script and failOpen is false.
Example:
error.data holds totalScore, riskLevel and signals.
Solutions:
- Review code for exfiltration patterns
- Avoid list→send sequences
- Use specific queries instead of wildcards
- Adjust scoring thresholds if false positive: the score is a heuristic
ENCLAVE_ERROR
Cause: A failure outside the sandbox before the script ran. The most common one is a syntax error:Failed to parse AgentScript code: ....
Solution: Fix the syntax of the script.
Validation Issues
Unknown global
Message:Unknown identifier "xyz". All identifiers must be either declared locally or in the allowed globals list. (code UNKNOWN_GLOBAL)
Cause: Code references an identifier not in the allowed globals list.
Solution: Use a tool instead, or give the enclave the value as a custom global:
@enclave-vm/ast on its own, list the name in allowedGlobals of the preset.
Blocked identifier
Message:Identifier 'process' is not allowed
Cause: Code uses a blocked identifier like process, eval, etc.
Solution: Remove the blocked identifier or use an allowed alternative.
Invalid loop type
Message:'while' loops are not allowed
Cause: Code uses a blocked loop type.
Solution: Use for or for-of instead:
User-defined function
Message:User-defined functions are not allowed
Cause: Code declares a function.
Solution: Use arrow functions in array methods or inline logic:
Pre-Scanner Errors
The enclave runs the pre-scanner with the preset named like its AST preset, so by default withagentscript: 100 KB of script in at most 1,000 lines of at most 2,000 characters, nesting depth 20, string literals of at most 10 KB, no regular-expression literal, no bidirectional or invisible control character. A script that needs more room gets it through the preScan option, for example preScan: { preset: 'standard' } (5 MB, 10,000 lines, nesting depth 50) or preScan: { config: { maxStringLength: 512 * 1024, maxLineLength: 100000 } }.
Input size exceeded
Message:Input size (...) exceeds maximum allowed (...) (code PRESCANNER_INPUT_TOO_LARGE)
Solution: Reduce code size.
Nesting depth exceeded
Message:Bracket nesting depth (51) exceeds maximum allowed (50) (code PRESCANNER_NESTING_OVERFLOW)
Solution: Simplify nested expressions.
Regular expression
Code:PRESCANNER_REDOS (a regex literal the pre-scanner rates as vulnerable), NO_REGEX_LITERAL or NO_REGEX_METHOD (the AgentScript rules)
Solution: AgentScript has no regular expressions. Use string methods with plain strings (includes, startsWith, split(',')), or let a tool do the matching.
Look-alike letter
Code:PRESCANNER_HOMOGRAPH
Cause: The script contains a letter from another script that looks like an ASCII letter (for example a Cyrillic а), anywhere in its text, string literals included.
Solution: Replace the letter. Text in such a script reaches a script through a tool result, not as a literal.
Connection Errors
Connection refused
Cause: The client cannot connect to the broker. Solutions:- Check the server is running
- Verify the URL is correct
- Check network/firewall settings
Session not found
Cause: Referencing an expired or invalid session. Solutions:- Sessions expire after completion
- Create a new session
- Check session ID is correct
Debugging Tips
Read the whole error
stack. The message is where the information is.
Log validation results
Track execution stats
Related
- Debugging - Debug techniques
- FAQ - Frequently asked questions
- Security Model - Understanding restrictions