crewAIInc/crewAI · error · BedrockValidationError

next_token must be between 1 and 2048 characters

Error message

next_token must be between 1 and 2048 characters

What it means

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.

Source

Thrown at lib/crewai-tools/src/crewai_tools/aws/bedrock/knowledge_base/retriever_tool.py:109

        try:
            if not self.knowledge_base_id:
                raise BedrockValidationError("knowledge_base_id cannot be empty")
            if not isinstance(self.knowledge_base_id, str):
                raise BedrockValidationError("knowledge_base_id must be a string")
            if len(self.knowledge_base_id) > 10:
                raise BedrockValidationError(
                    "knowledge_base_id must be 10 characters or less"
                )
            if not all(c.isalnum() for c in self.knowledge_base_id):
                raise BedrockValidationError(
                    "knowledge_base_id must contain only alphanumeric characters"
                )

            if self.next_token:
                if not isinstance(self.next_token, str):
                    raise BedrockValidationError("next_token must be a string")
                if len(self.next_token) < 1 or len(self.next_token) > 2048:
                    raise BedrockValidationError(
                        "next_token must be between 1 and 2048 characters"
                    )
                if " " in self.next_token:
                    raise BedrockValidationError("next_token cannot contain spaces")

            if self.number_of_results is not None:
                if not isinstance(self.number_of_results, int):
                    raise BedrockValidationError("number_of_results must be an integer")
                if self.number_of_results < 1:
                    raise BedrockValidationError(
                        "number_of_results must be greater than 0"
                    )

        except BedrockValidationError as e:
            raise BedrockValidationError(f"Parameter validation failed: {e!s}") from e

    def _process_retrieval_result(self, result: dict[str, Any]) -> dict[str, Any]:
        """Process a single retrieval result from Bedrock Knowledge Base.

View on GitHub (pinned to 754d7323be)

Solutions

  1. Trim the token before passing: next_token=resp['nextToken'].strip()
  2. Verify the token came from the same knowledge base retrieve call's response payload
  3. If token is empty/None, omit next_token entirely instead of passing an empty string
  4. Check len(token) <= 2048 before retrying

Example fix

# before
tool._run_with_next_token(query, next_token=raw_token)
# after
next_token = (raw_token or "").strip()
if next_token:
    tool._run_with_next_token(query, next_token=next_token)
Defensive patterns

Strategy: validation

Validate before calling

token = (token or '').strip()
if token and not (1 <= len(token) <= 2048):
    raise ValueError(f'next_token length {len(token)} out of range 1-2048')

Type guard

def is_valid_next_token(t: object) -> bool:
    return isinstance(t, str) and 1 <= len(t) <= 2048

Try / catch

from crewai_tools.aws.bedrock.knowledge_base.retriever_tool import BedrockValidationError
try:
    out = tool._run(q)
except BedrockValidationError as e:
    if 'next_token must be between' in str(e):
        tool.next_token = None  # drop bad token, restart pagination
        out = tool._run(q)
    else:
        raise

Prevention

When it happens

Trigger: 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.

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

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/ece31c3299cb7470. Report an issue: GitHub.