{"record":{"id":"ece31c3299cb7470","repo":"crewAIInc/crewAI","slug":"next-token-must-be-between-1-and-2048-characters","errorCode":null,"errorMessage":"next_token must be between 1 and 2048 characters","messagePattern":"next_token must be between 1 and 2048 characters","errorType":"validation","errorClass":"BedrockValidationError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/aws/bedrock/knowledge_base/retriever_tool.py","lineNumber":109,"sourceCode":"        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\n    def _process_retrieval_result(self, result: dict[str, Any]) -> dict[str, Any]:\n        \"\"\"Process a single retrieval result from Bedrock Knowledge Base.","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/aws/bedrock/knowledge_base/retriever_tool.py#L91-L127","documentation":"Raised by BedrockKnowledgeBaseRetrievalTool when the optional next_token parameter is set but its length is outside the AWS-documented 1-2048 character range. Bedrock Agent Runtime retrieve APIs reject out-of-range pagination tokens, so the tool validates up front and wraps the failure as BedrockValidationError (later re-wrapped as 'Parameter validation failed'). It fires in _run() before any AWS call is made.","triggerScenarios":"Passing next_token='' (empty string is truthy check bypassed only if falsy, but a 1-char minimum fails for empty-after-strip strings), a truncated/corrupted token >2048 chars, or a token copied with extra characters into BedrockKnowledgeBaseRetrievalTool(next_token=...) or via tool input.","commonSituations":"Copying a nextToken from a raw API response or log line and pasting it with quotes/whitespace appended; passing a token from a different AWS service; token corrupted by JSON double-encoding growing past 2048 chars.","solutions":["Trim the token before passing: next_token=resp['nextToken'].strip()","Verify the token came from the same knowledge base retrieve call's response payload","If token is empty/None, omit next_token entirely instead of passing an empty string","Check len(token) <= 2048 before retrying"],"exampleFix":"# before\ntool._run_with_next_token(query, next_token=raw_token)\n# after\nnext_token = (raw_token or \"\").strip()\nif next_token:\n    tool._run_with_next_token(query, next_token=next_token)","handlingStrategy":"validation","validationCode":"token = (token or '').strip()\nif token and not (1 <= len(token) <= 2048):\n    raise ValueError(f'next_token length {len(token)} out of range 1-2048')","typeGuard":"def is_valid_next_token(t: object) -> bool:\n    return isinstance(t, str) and 1 <= len(t) <= 2048","tryCatchPattern":"from crewai_tools.aws.bedrock.knowledge_base.retriever_tool import BedrockValidationError\ntry:\n    out = tool._run(q)\nexcept BedrockValidationError as e:\n    if 'next_token must be between' in str(e):\n        tool.next_token = None  # drop bad token, restart pagination\n        out = tool._run(q)\n    else:\n        raise","preventionTips":["Pass nextToken straight from the previous response object, never retype it","Strip and length-check tokens before constructing the tool","Treat pagination tokens as opaque — never truncate or join them"],"tags":["aws","bedrock","validation","pagination"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}