iflytek/astron-agent · warning · ProtocolParamException

Invalid separator format

Error message

Invalid separator format: {e}；The separator must be an array of strings

What it means

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.

Solutions

1. Serialize with JSON.stringify / json.dumps: separator=%5B%22%5Cn%22%5D for ["\n"].
2. Replace single quotes with double quotes — JSON only accepts double-quoted strings.
3. When using curl, wrap the value in single quotes and rely on --data-urlencode to preserve encoding.
4. Round-trip the value through JSON.parse client-side to validate before sending.

Example fix

// before
curl ... --data 'separator=["\n"]'   # shell mangles quotes/backslash
// after
curl ... --data-urlencode 'separator=["\n","."]'

import json
def valid_separator_json(raw: str) -> bool:
    try:
        val = json.loads(raw)
    except (json.JSONDecodeError, ValueError):
        return False
    return isinstance(val, list) and all(isinstance(x, str) for x in val)
# e.g. valid_separator_json('["\\n","."]') -> True

def parses_as_json(raw) -> bool:
    try:
        json.loads(raw); return True
    except Exception:
        return False

When it happens

Trigger: file_upload receives separator values like '\n' (single unescaped newline, not JSON), 'a,b', or "['\n','.',']" — single-quoted pseudo-JSON that json.loads rejects.

Common situations: 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.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

• The lengthRange must be an array of integers
• Invalid lengthRange format
• The separator must be an array of strings
• PARAMS_ERROR
• PARAMETER_ERROR

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

Appendix: source

Thrown at core/knowledge/api/v1/api.py:288

        except (json.JSONDecodeError, ValueError) as e:
            raise ProtocolParamException(
                msg=f"Invalid lengthRange format: {str(e)}；The lengthRange must be an array of integers"
            )
    return parsed_length_range


async def parse_separator(separator: Optional[str]) -> Optional[List[str]]:
    parsed_separator = None
    if separator:
        try:
            parsed_separator = json.loads(separator)
            # Invalid
            if not all(isinstance(x, str) for x in parsed_separator):
                raise ProtocolParamException(
                    msg="The separator must be an array of strings"
                )
        except (json.JSONDecodeError, ValueError) as e:
            raise ProtocolParamException(
                msg=f"Invalid separator format: {str(e)}；The separator must be an array of strings"
            )
    return parsed_separator


@rag_router.post("/document/upload")
async def file_upload(
    file: UploadFile = File(),
    ragType: RAGType = Form(),
    lengthRange: Optional[str] = Form(
        None, description='Length range JSON array, such as "[256, 1024]"'
    ),
    separator: Optional[str] = Form(
        None, description='Delimiter JSON array, such as ["\\n", ". "]'
    ),
    documentId: Optional[str] = Form(
        None,
        description=(

View on GitHub (pinned to 5e758547a8)