{"record":{"id":"c10ab67079187ade","repo":"iflytek/astron-agent","slug":"invalid-separator-format-e-the-separator-must-be-an-array-of","errorCode":null,"errorMessage":"Invalid separator format: {e}；The separator must be an array of strings","messagePattern":"Invalid separator format: (.+?)；The separator must be an array of strings","errorType":"validation","errorClass":"ProtocolParamException","httpStatus":400,"severity":"warning","filePath":"core/knowledge/api/v1/api.py","lineNumber":288,"sourceCode":"        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\", \". \"]'\n    ),\n    documentId: Optional[str] = Form(\n        None,\n        description=(","sourceCodeStart":270,"sourceCodeEnd":306,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/api/v1/api.py#L270-L306","documentation":"ProtocolParamException raised by parse_separator when the separator parameter is not valid JSON — json.loads raises JSONDecodeError (or ValueError) and the API reports the raw parse error plus the expected format: an array of strings.","triggerScenarios":"file_upload receives separator values like '\\n' (single unescaped newline, not JSON), 'a,b', or \"['\\n','.',']\" — single-quoted pseudo-JSON that json.loads rejects.","commonSituations":"Passing Python list reprs (single quotes) instead of json.dumps output; shell/curl dropping quotes so brackets/newlines never arrive; clients URL-encoding newlines incorrectly; copying separators from config without JSON serialization.","solutions":["Serialize with JSON.stringify / json.dumps: separator=%5B%22%5Cn%22%5D for [\"\\n\"].","Replace single quotes with double quotes — JSON only accepts double-quoted strings.","When using curl, wrap the value in single quotes and rely on --data-urlencode to preserve encoding.","Round-trip the value through JSON.parse client-side to validate before sending."],"exampleFix":"// before\ncurl ... --data 'separator=[\"\\n\"]'   # shell mangles quotes/backslash\n// after\ncurl ... --data-urlencode 'separator=[\"\\n\",\".\"]'","handlingStrategy":"validation","validationCode":"import json\ndef valid_separator_json(raw: str) -> bool:\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# e.g. valid_separator_json('[\"\\\\n\",\".\"]') -> True","typeGuard":"def parses_as_json(raw) -> bool:\n    try:\n        json.loads(raw); return True\n    except Exception:\n        return False","tryCatchPattern":null,"preventionTips":["Use double quotes in JSON strings — single-quoted Python-style lists are invalid JSON.","Escape control characters like newline as \\n inside JSON strings.","Use --data-urlencode with curl and single-quote the JSON payload.","Round-trip through json.loads/JSON.parse as a pre-send sanity check."],"tags":["validation","json","request-params","knowledge"],"backgroundTag":"json-parse-error","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"}