huggingface/smolagents · error · InterpreterError

The variable `{name.id}` is not defined.

Error message

The variable `{name.id}` is not defined.

What it means

The sandboxed interpreter could not resolve a Name node: the identifier is not in local state, not a static/custom tool, and not in the ERRORS mapping (built-in exception classes). Note it first tries difflib close matches against state before failing — but only returns a close match if one exists.

Source

Thrown at src/smolagents/local_python_executor.py:959

def evaluate_name(
    name: ast.Name,
    state: dict[str, Any],
    static_tools: dict[str, Callable],
    custom_tools: dict[str, Callable],
    authorized_imports: list[str],
) -> Any:
    if name.id in state:
        return state[name.id]
    elif name.id in static_tools:
        return safer_func(static_tools[name.id], static_tools=static_tools, authorized_imports=authorized_imports)
    elif name.id in custom_tools:
        return custom_tools[name.id]
    elif name.id in ERRORS:
        return ERRORS[name.id]
    close_matches = difflib.get_close_matches(name.id, list(state.keys()))
    if len(close_matches) > 0:
        return state[close_matches[0]]
    raise InterpreterError(f"The variable `{name.id}` is not defined.")


def evaluate_condition(
    condition: ast.Compare,
    state: dict[str, Any],
    static_tools: dict[str, Callable],
    custom_tools: dict[str, Callable],
    authorized_imports: list[str],
) -> bool | object:
    result = True
    left = evaluate_ast(condition.left, state, static_tools, custom_tools, authorized_imports)
    for i, (op, comparator) in enumerate(zip(condition.ops, condition.comparators)):
        op = type(op)
        right = evaluate_ast(comparator, state, static_tools, custom_tools, authorized_imports)
        if op == ast.Eq:
            current_result = left == right
        elif op == ast.NotEq:
            current_result = left != right

View on GitHub (pinned to 30bb116109)

Solutions

1. Define the variable before use in the same code block (state is per-run)
2. Check spelling of tools and variables; the close-match fallback only works for near-identical names
3. For exception classes, only use those exposed by the interpreter's ERRORS mapping (standard builtins)

Example fix

# before
total = price + quantty  # typo
# after
total = price + quantity

# generated code: check before use
if 'target_var' not in dir_var_names:  # or track defined names explicitly
    target_var = compute_default()

try:
    evaluate_python(code, ...)
except InterpreterError as e:
    if 'is not defined' in str(e):
        # ask the model/agent to define the variable in this block, retry

When it happens

Trigger: Using an undefined variable, a NameError in normal Python; referencing a tool by the wrong name; using an exception class not in the interpreter's ERRORS whitelist (e.g. some third-party exception).

Common situations: Agent code references a variable defined in a different script run (state doesn't persist between executor runs); typo in variable name where no close match exists; expecting builtins like __import__ or exception classes not whitelisted.

Related errors

• Cannot delete name '{target.id}': name is not defined
• Error during jinja template rendering: {type(e).__name__}: {
• Cannot unpack non-dict value in **kwargs: {type(starred_dict
• super() needs at least one argument
• super() argument 1 must be type

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/2648a2249f26c20b. Report an issue: GitHub.