{"record":{"id":"b668bd6676f3594c","repo":"crewAIInc/crewAI","slug":"next-token-must-be-a-string","errorCode":null,"errorMessage":"next_token must be a string","messagePattern":"next_token must be a string","errorType":"validation","errorClass":"BedrockValidationError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/aws/bedrock/knowledge_base/retriever_tool.py","lineNumber":107,"sourceCode":"    def _validate_parameters(self) -> None:\n        \"\"\"Validate the parameters according to AWS API requirements.\"\"\"\n        try:\n            if not self.knowledge_base_id:\n                raise BedrockValidationError(\"knowledge_base_id cannot be empty\")\n            if not isinstance(self.knowledge_base_id, str):\n                raise BedrockValidationError(\"knowledge_base_id must be a string\")\n            if len(self.knowledge_base_id) > 10:\n                raise BedrockValidationError(\n                    \"knowledge_base_id must be 10 characters or less\"\n                )\n            if not all(c.isalnum() for c in self.knowledge_base_id):\n                raise BedrockValidationError(\n                    \"knowledge_base_id must contain only alphanumeric characters\"\n                )\n\n            if self.next_token:\n                if not isinstance(self.next_token, str):\n                    raise BedrockValidationError(\"next_token must be a string\")\n                if len(self.next_token) < 1 or len(self.next_token) > 2048:\n                    raise BedrockValidationError(\n                        \"next_token must be between 1 and 2048 characters\"\n                    )\n                if \" \" in self.next_token:\n                    raise BedrockValidationError(\"next_token cannot contain spaces\")\n\n            if self.number_of_results is not None:\n                if not isinstance(self.number_of_results, int):\n                    raise BedrockValidationError(\"number_of_results must be an integer\")\n                if self.number_of_results < 1:\n                    raise BedrockValidationError(\n                        \"number_of_results must be greater than 0\"\n                    )\n\n        except BedrockValidationError as e:\n            raise BedrockValidationError(f\"Parameter validation failed: {e!s}\") from e\n","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/aws/bedrock/knowledge_base/retriever_tool.py#L89-L125","documentation":"A BedrockValidationError raised when the optional next_token parameter is truthy but not a str. next_token is AWS's pagination cursor returned by a previous Retrieve call; the tool only type-checks it when provided, then further validates length (1-2048) and absence of spaces in the following checks.","triggerScenarios":"Passing next_token as bytes, a dict, or an int — e.g. forwarding a raw header value or the whole previous response object instead of the string 'nextToken' field. Only fires when next_token is non-empty.","commonSituations":"Chaining Retrieve calls programmatically and passing response['nextToken'] from a JSON-decoded source that kept it as bytes; passing the entire response dict by mistake; test fixtures with placeholder tokens of the wrong type.","solutions":["Extract and pass the string field: next_token=prev_response.get('nextToken') (it is already str in parsed JSON).","Coerce with str(next_token) if the source is bytes.","Omit next_token when there is no prior page."],"exampleFix":"# before\nresult = tool._run(query=\"...\", next_token=prev_response)  # dict\n\n# after\nresult = tool._run(query=\"...\", next_token=prev_response[\"nextToken\"])  # str or None","handlingStrategy":"type-guard","validationCode":"if next_token is not None and not isinstance(next_token, str):\n    next_token = str(next_token)","typeGuard":"def is_next_token(v) -> bool:\n    return v is None or (isinstance(v, str) and 1 <= len(v) <= 2048 and \" \" not in v)","tryCatchPattern":"try:\n    tool = BedrockKBRetrieverTool(knowledge_base_id=kb_id, next_token=next_token)\nexcept BedrockValidationError as e:\n    if \"next_token\" in str(e):\n        raise ValueError(\"Pass response['nextToken'] (a str) or omit it\") from e\n    raise","preventionTips":["Forward only the string 'nextToken' field from previous Retrieve responses.","Omit next_token on the first page.","Remember the sibling rules: length 1-2048 and no spaces."],"tags":["aws","bedrock","knowledge-base","pagination","type-error"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}