BerriAI/litellm · error · ValueError

Invalid model format. Expected format…

Error message

Invalid model format. Expected format: 'model=bedrock/agentcore/arn:aws:bedrock-agentcore:region:account:runtime/runtime_id'

What it means

Bedrock AgentCore chat requires the model string to start with the literal prefix 'agentcore/' followed by the full runtime ARN. _get_agent_runtime_arn splits the model on the first '/' and raises this ValueError when the prefix is missing, wrong, or there is no slash at all. It fires before any network call, so it is purely a caller-input/config error.

Solutions

Use the full router form model="bedrock/agentcore/<runtime-arn>" (or "agentcore/<runtime-arn>" if calling the Bedrock provider directly)
Copy the runtime ARN verbatim from the Bedrock AgentCore console — it must contain the arn:aws:bedrock-agentcore:region:account:runtime/<id> shape
If routing through the LiteLLM proxy, put the correctly formatted three-segment string in the deployment's model_name, not just the ARN

Example fix

// before
resp = litellm.completion(model="arn:aws:bedrock-agentcore:us-west-2:888602223428:runtime/hosted_agent_r9jvp", messages=msgs)

// after
resp = litellm.completion(model="bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:888602223428:runtime/hosted_agent_r9jvp", messages=msgs)

Defensive patterns

Strategy: validation

Validate before calling

model = "bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:888602223428:runtime/hosted_agent_x"
_, _, rest = model.split("/", 2)
if not rest.startswith("agentcore/"):
    raise ValueError(f"model must be 'bedrock/agentcore/<runtime-arn>', got {model!r}")
resp = litellm.completion(model=model, messages=msgs)

Type guard

def is_agentcore_model_string(model: str) -> bool:
    """True when model carries the required 'agentcore/<arn>' shape."""
    parts = model.split("/", 1)
    return len(parts) == 2 and parts[0] == "agentcore"

Try / catch

try:
    resp = litellm.completion(model=model, messages=msgs)
except ValueError as e:
    if "Invalid model format" in str(e) and "agentcore" in str(e):
        raise ConfigError(f"Fix deployment config: use bedrock/agentcore/<runtime-arn>, got {model!r}") from e
    raise

Prevention

Centralize AgentCore model strings in one config module with a documented format
Copy runtime ARNs from the AgentCore console, never type them by hand
Add config validation at app startup for every bedrock/agentcore model entry

When it happens

Trigger: litellm.completion with model="arn:aws:bedrock-agentcore:us-west-2:123:runtime/abc" (bare ARN, no prefix); model="agentcore" (no slash); model="bedrock-agentcore/arn:..." or any other first component that is not exactly 'agentcore'.

Common situations: Porting code from boto3 bedrock-agentcore where the bare ARN is accepted; pasting the runtime ARN from the AgentCore console straight into model; typos in the prefix; proxy deployment configs that store only the ARN in the model field.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/bbd2768eec8265f5. Report an issue: GitHub.

Appendix: source

Thrown at litellm/llms/bedrock/chat/agentcore/transformation.py:163

            headers=headers,
            optional_params=optional_params,
            request_data=request_data,
            api_base=api_base,
            model=model,
            stream=stream,
            fake_stream=fake_stream,
            api_key=api_key,
        )

    def _get_agent_runtime_arn(self, model: str) -> str:
        """
        Extract ARN from model string
        model = "agentcore/arn:aws:bedrock-agentcore:us-west-2:888602223428:runtime/hosted_agent_r9jvp-3ySZuRHjLC"
        returns: "arn:aws:bedrock-agentcore:us-west-2:888602223428:runtime/hosted_agent_r9jvp-3ySZuRHjLC"
        """
        parts: Final = model.split("/", 1)
        if len(parts) != 2 or parts[0] != "agentcore":
            raise ValueError(
                "Invalid model format. Expected format: 'model=bedrock/agentcore/arn:aws:bedrock-agentcore:region:account:runtime/runtime_id'"
            )
        return parts[1]

    def _extract_region_from_arn(self, arn: str) -> str:
        """
        Extract region from ARN
        arn:aws:bedrock-agentcore:us-west-2:888602223428:runtime/hosted_agent_r9jvp-3ySZuRHjLC
        returns: us-west-2
        """
        parts: Final = arn.split(":")
        if len(parts) >= 4:
            return parts[3]
        raise ValueError(f"Invalid ARN format: {arn}")

    def _get_runtime_session_id(self, optional_params: dict) -> str:
        """
        Get or generate runtime session ID (must be 33+ chars)

View on GitHub (pinned to 77b7c6c40c)