{"record":{"id":"94c0dacfc15107ac","repo":"iflytek/astron-agent","slug":"the-separator-must-be-an-array-of-strings","errorCode":null,"errorMessage":"The separator must be an array of strings","messagePattern":"The separator must be an array of strings","errorType":"validation","errorClass":"ProtocolParamException","httpStatus":400,"severity":"warning","filePath":"core/knowledge/api/v1/api.py","lineNumber":284,"sourceCode":"            if not all(isinstance(x, int) for x in parsed_length_range):\n                raise ProtocolParamException(\n                    msg=\"The lengthRange must be an array of integers\"\n                )\n        except (json.JSONDecodeError, ValueError) as e:\n            raise ProtocolParamException(\n                msg=f\"Invalid lengthRange format: {str(e)}；The lengthRange must be an array of integers\"\n            )\n    return parsed_length_range\n\n\nasync def parse_separator(separator: Optional[str]) -> Optional[List[str]]:\n    parsed_separator = None\n    if separator:\n        try:\n            parsed_separator = json.loads(separator)\n            # Invalid\n            if not all(isinstance(x, str) for x in parsed_separator):\n                raise ProtocolParamException(\n                    msg=\"The separator must be an array of strings\"\n                )\n        except (json.JSONDecodeError, ValueError) as e:\n            raise ProtocolParamException(\n                msg=f\"Invalid separator format: {str(e)}；The separator must be an array of strings\"\n            )\n    return parsed_separator\n\n\n@rag_router.post(\"/document/upload\")\nasync def file_upload(\n    file: UploadFile = File(),\n    ragType: RAGType = Form(),\n    lengthRange: Optional[str] = Form(\n        None, description='Length range JSON array, such as \"[256, 1024]\"'\n    ),\n    separator: Optional[str] = Form(\n        None, description='Delimiter JSON array, such as [\"\\\\n\", \". \"]'","sourceCodeStart":266,"sourceCodeEnd":302,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/api/v1/api.py#L266-L302","documentation":"parse_separator raises ProtocolParamException when the separator query parameter is provided but is not a JSON array of strings. It is a request-parameter guard on the knowledge file_upload endpoint; malformed JSON or wrong element types trigger it.","triggerScenarios":"file_upload receives separator='[1,2]' or '[null]' or '[true]' — json.loads succeeds but all(isinstance(x, str)) fails, raising ProtocolParamException.","commonSituations":"Clients sending numeric chunk keys or unquoted tokens as separators; JSON produced by joining non-string arrays; template engines coercing strings to numbers; users passing regex fragments unquoted.","solutions":["Send every element as a JSON string: separator=[\"\\n\",\".\"] URL-encoded.","Coerce on the client before sending: JSON.stringify(separators.map(String)).","If numeric separators are intended, convert them to strings at the source (the API treats separators as text delimiters).","Validate with JSON.parse(...).every(x => typeof x === 'string') before the request."],"exampleFix":"// before\nconst seps = [1, 2];\nbody.append('separator', JSON.stringify(seps)); // [1,2] rejected\n// after\nconst seps = ['\\n', '.'];\nbody.append('separator', JSON.stringify(seps.map(String)));","handlingStrategy":"validation","validationCode":"import json\ndef valid_separator(raw):\n    try:\n        val = json.loads(raw)\n    except (json.JSONDecodeError, ValueError):\n        return False\n    return isinstance(val, list) and all(isinstance(x, str) for x in val)\n# call the API only if valid_separator(separator_param)","typeGuard":"def is_str_array(val) -> bool:\n    return isinstance(val, list) and all(isinstance(x, str) for x in val)","tryCatchPattern":null,"preventionTips":["Map client-side separator values with String()/str() before serialization.","Keep separators as text constants in one place to avoid accidental numeric coercion.","Validate with JSON.parse + every(typeof === 'string') before the request.","Document expected separator format in the upload API client SDK."],"tags":["validation","request-params","knowledge","json"],"backgroundTag":"schema-validation-failed","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}