iflytek/astron-agent · warning · ProtocolParamException

The separator must be an array of strings

Error message

The separator must be an array of strings

What it means

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.

Solutions

1. Send every element as a JSON string: separator=["\n","."] URL-encoded.
2. Coerce on the client before sending: JSON.stringify(separators.map(String)).
3. If numeric separators are intended, convert them to strings at the source (the API treats separators as text delimiters).
4. Validate with JSON.parse(...).every(x => typeof x === 'string') before the request.

Example fix

// before
const seps = [1, 2];
body.append('separator', JSON.stringify(seps)); // [1,2] rejected
// after
const seps = ['\n', '.'];
body.append('separator', JSON.stringify(seps.map(String)));

import json
def valid_separator(raw):
    try:
        val = json.loads(raw)
    except (json.JSONDecodeError, ValueError):
        return False
    return isinstance(val, list) and all(isinstance(x, str) for x in val)
# call the API only if valid_separator(separator_param)

def is_str_array(val) -> bool:
    return isinstance(val, list) and all(isinstance(x, str) for x in val)

When it happens

Trigger: file_upload receives separator='[1,2]' or '[null]' or '[true]' — json.loads succeeds but all(isinstance(x, str)) fails, raising ProtocolParamException.

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

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

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

Appendix: source

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

            if not all(isinstance(x, int) for x in parsed_length_range):
                raise ProtocolParamException(
                    msg="The lengthRange must be an array of integers"
                )
        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", ". "]'

View on GitHub (pinned to 5e758547a8)