iflytek/astron-agent · error · CustomException

ENG_PROTOCOL_VALIDATE_ERROR

ENG_PROTOCOL_VALIDATE_ERROR

Error message

Error: {file_var_name} is a required parameter

What it means

ENG_PROTOCOL_VALIDATE_ERROR raised in chat_service._validate_file_inputs when a workflow variable marked is_required of file type is absent from chat_vo.parameters. The chat request's parameter set fails the workflow's file-input protocol validation before _run proceeds.

Solutions

1. Include the required file variable in the chat request's parameters
2. Check the workflow's file variable list and supply every variable flagged required
3. Confirm the parameter key name matches the workflow variable exactly (case-sensitive)
4. If the variable should be optional, set is_required=false on the workflow file variable

Example fix

// before
POST /chat {"parameters": {}}
// after
POST /chat {"parameters": {"my_file": {"file_id": "..."}}}  # supply required file param

required_files = [v.name for v in workflow.file_variables if v.is_required]
missing = [n for n in required_files if n not in request.parameters]
if missing:
    raise ValueError(f'missing required file parameters: {missing}')

try:
    chat_response = client.chat(chat_vo)
except CustomException as e:
    if e.err_code == CodeEnum.ENG_PROTOCOL_VALIDATE_ERROR:
        # parse the variable name from e.err_msg and prompt the user to attach the file
        return error_response(400, e.err_msg)
    raise

When it happens

Trigger: Invoking the chat/run API without supplying a required file parameter — the workflow defines a required file-type variable but the request's parameters dict omits that key.

Common situations: Client not updated after the workflow added a new required file input, file upload step skipped in the UI, parameter name typo between client payload and workflow variable name.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• 21602
• 8008
• 8008
• APPID_CANNOT_EMPTY
• Chat ID cannot be empty

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

Appendix: source

Thrown at core/workflow/service/chat_service.py:291

    :return: None
    :raises CustomException: When file validation fails or
                             required parameters are missing
    """
    from workflow.engine.entities.file import File

    file_info_list, has_file = await File.has_file_in_dsl(workflow_dsl, span_context)
    if not has_file:
        return

    for file_info in file_info_list:
        file_var_name = file_info.file_var_name
        file_var_type = file_info.file_var_type
        is_required = file_info.is_required

        # Check required parameters
        if file_var_name not in chat_vo.parameters:
            if is_required:
                raise CustomException(
                    err_code=CodeEnum.ENG_PROTOCOL_VALIDATE_ERROR,
                    err_msg=f"Error: {file_var_name} is a required parameter",
                )
            continue

        param_value = chat_vo.parameters[file_var_name]

        # Check empty values (skip if not required)
        if not param_value and not is_required:
            continue

        # Validate files based on type
        if file_var_type == "string":
            await File.check_file_var_isvalid(
                param_value, file_info.allowed_file_type, span_context
            )
        elif file_var_type == "array":
            for input_file in param_value:

View on GitHub (pinned to 5e758547a8)