iflytek/astron-agent · error · ValueError

invalid system variable value

Error message

invalid system variable value {value}

What it means

SystemVariable.value_of maps a raw value to a SystemVariable enum member and raises ValueError('invalid system variable value {value}') when the value matches none of them. The library throws this to reject references to system variables (like workflow-level built-ins) that do not exist in this engine version, preventing undefined-variable resolution later during execution.

Solutions

  1. Correct the system variable name to one defined in the SystemVariable enum
  2. Check the engine version docs for renamed/removed system variables and update the DSL
  3. Upgrade the engine if the referenced variable exists only in newer releases
  4. Enumerate cls members (or the docs) to see the exact accepted values before authoring references

Example fix

# before
"valueRef": "sys.workflow_conversation_id"  # not a member
# after
"valueRef": "sys.conversation_id"
Defensive patterns

Strategy: validation

Validate before calling

from core.workflow.engine.entities.node_entities import SystemVariable
valid = {sv.value for sv in SystemVariable}
assert var_ref.split(".")[-1] in valid, f"unknown system variable {var_ref}"

Type guard

def is_known_system_variable(value) -> bool:
    try:
        SystemVariable.value_of(value)
        return True
    except ValueError:
        return False

Try / catch

try:
    sv = SystemVariable.value_of(raw)
except ValueError as e:
    log.warning("bad system variable reference: %s", raw)
    raise VariableResolutionError(str(e)) from e

Prevention

When it happens

Trigger: A DSL or variable reference uses a system variable name that is not part of the SystemVariable enum — misspelled names, renamed system variables across versions, or variables referenced from another platform's DSL.

Common situations: Version migration where a system variable was renamed or removed; hand-written expressions referencing system variables with wrong casing; DSLs ported from a different workflow product.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/12c2a75684ab29dc. Report an issue: GitHub.

Appendix: source

Thrown at core/workflow/engine/entities/node_entities.py:76

    QUERY = "query"
    FILES = "files"
    CONVERSATION_ID = "conversation_id"
    USER_ID = "user_id"

    @classmethod
    def value_of(cls, value: str) -> "SystemVariable":
        """
        Get SystemVariable enum from string value.

        :param value: System variable string value
        :return: Corresponding SystemVariable enum
        :raises ValueError: If the value is not a valid system variable
        """
        for system_variable in cls:
            if system_variable.value == value:
                return system_variable
        raise ValueError(f"invalid system variable value {value}")


class NodeRunMetadataKey(Enum):
    """
    Enumeration of metadata keys for node execution tracking.
    """

    TOTAL_TOKENS = "total_tokens"
    TOTAL_PRICE = "total_price"
    CURRENCY = "currency"
    TOOL_INFO = "tool_info"
    ITERATION_ID = "iteration_id"
    ITERATION_INDEX = "iteration_index"


# Node types that continue execution on error without streaming
CONTINUE_ON_ERROR_NOT_STREAM_NODE_TYPE = [
    NodeType.DATABASE.value,

View on GitHub (pinned to 5e758547a8)