{"record":{"id":"bb58343fce583a23","repo":"iflytek/astron-agent","slug":"eng-protocol-validate-error-file-var-name-is-a-required","errorCode":"ENG_PROTOCOL_VALIDATE_ERROR","errorMessage":"Error: {file_var_name} is a required parameter","messagePattern":"Error: (.+?) is a required parameter","errorType":"validation","errorClass":"CustomException","httpStatus":null,"severity":"error","filePath":"core/workflow/service/chat_service.py","lineNumber":291,"sourceCode":"    :return: None\n    :raises CustomException: When file validation fails or\n                             required parameters are missing\n    \"\"\"\n    from workflow.engine.entities.file import File\n\n    file_info_list, has_file = await File.has_file_in_dsl(workflow_dsl, span_context)\n    if not has_file:\n        return\n\n    for file_info in file_info_list:\n        file_var_name = file_info.file_var_name\n        file_var_type = file_info.file_var_type\n        is_required = file_info.is_required\n\n        # Check required parameters\n        if file_var_name not in chat_vo.parameters:\n            if is_required:\n                raise CustomException(\n                    err_code=CodeEnum.ENG_PROTOCOL_VALIDATE_ERROR,\n                    err_msg=f\"Error: {file_var_name} is a required parameter\",\n                )\n            continue\n\n        param_value = chat_vo.parameters[file_var_name]\n\n        # Check empty values (skip if not required)\n        if not param_value and not is_required:\n            continue\n\n        # Validate files based on type\n        if file_var_type == \"string\":\n            await File.check_file_var_isvalid(\n                param_value, file_info.allowed_file_type, span_context\n            )\n        elif file_var_type == \"array\":\n            for input_file in param_value:","sourceCodeStart":273,"sourceCodeEnd":309,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/workflow/service/chat_service.py#L273-L309","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Include the required file variable in the chat request's parameters","Check the workflow's file variable list and supply every variable flagged required","Confirm the parameter key name matches the workflow variable exactly (case-sensitive)","If the variable should be optional, set is_required=false on the workflow file variable"],"exampleFix":"// before\nPOST /chat {\"parameters\": {}}\n// after\nPOST /chat {\"parameters\": {\"my_file\": {\"file_id\": \"...\"}}}  # supply required file param","handlingStrategy":"validation","validationCode":"required_files = [v.name for v in workflow.file_variables if v.is_required]\nmissing = [n for n in required_files if n not in request.parameters]\nif missing:\n    raise ValueError(f'missing required file parameters: {missing}')","typeGuard":null,"tryCatchPattern":"try:\n    chat_response = client.chat(chat_vo)\nexcept CustomException as e:\n    if e.err_code == CodeEnum.ENG_PROTOCOL_VALIDATE_ERROR:\n        # parse the variable name from e.err_msg and prompt the user to attach the file\n        return error_response(400, e.err_msg)\n    raise","preventionTips":["Keep the client's parameter schema in sync with the workflow's variable definitions","Upload files first and reference them by id in parameters","Match parameter keys exactly (case-sensitive) to workflow variable names","Mark file variables optional (is_required=false) when they are not always needed"],"tags":["validation","chat","workflow","file-input"],"backgroundTag":"missing-required-argument","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}