NousResearch/hermes-agent · error · ImportError

The 'boto3' package is required for the AWS Bedrock provider

Error message

The 'boto3' package is required for the AWS Bedrock provider. Install it with: pip install boto3
Or install Hermes with Bedrock support: pip install -e '.[bedrock]'

What it means

The AWS Bedrock adapter requires boto3. _require_boto3() imports it and converts the failure into an ImportError with two install paths (plain boto3 or Hermes' [bedrock] extra). No Bedrock call can proceed until the SDK is present.

Source

Thrown at agent/bedrock_adapter.py:69

# ---------------------------------------------------------------------------
# Lazy boto3 import — only loaded when the Bedrock provider is actually used.
# This keeps startup fast for users who don't use Bedrock.
# ---------------------------------------------------------------------------

_bedrock_runtime_client_cache: Dict[str, Any] = {}
_bedrock_control_client_cache: Dict[str, Any] = {}


_MIN_BOTO3_VERSION = (1, 34, 59)


def _require_boto3():
    """Import boto3, raising a clear error if not installed or too old."""
    try:
        import boto3
    except ImportError:
        raise ImportError(
            "The 'boto3' package is required for the AWS Bedrock provider. "
            "Install it with: pip install boto3\n"
            "Or install Hermes with Bedrock support: pip install -e '.[bedrock]'"
        )
    # converse() / converse_stream() were added in boto3 1.34.59.
    # When Hermes is installed editable into system Python, the system boto3
    # (e.g. Ubuntu 24.04 ships 1.34.46) may take precedence over the venv
    # version pinned in pyproject.toml.
    try:
        version = tuple(int(x) for x in boto3.__version__.split(".")[:3])
    except (AttributeError, ValueError):
        return boto3  # can't parse — don't block on version check
    if version < _MIN_BOTO3_VERSION:
        raise RuntimeError(
            f"boto3 {boto3.__version__} does not support converse_stream "
            f"(minimum 1.34.59 required). Upgrade with: "
            f"pip install --upgrade boto3"
        )

View on GitHub (pinned to c896c09c42)

Solutions

pip install -e '.[bedrock]' (installs boto3 with the Hermes extra) or pip install boto3.
Confirm the install landed in the venv Hermes actually runs from (which hermes; hermes -c 'import boto3').
Re-run `hermes setup` after installing so provider detection includes Bedrock.

Example fix

pip install -e '.[bedrock]'   # or: pip install boto3

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("boto3") is None:
    raise SystemExit("Bedrock selected but boto3 missing — pip install -e '.[bedrock]'")

Try / catch

try:
    from agent.bedrock_adapter import _require_boto3
    _require_boto3()
except ImportError as e:
    if "boto3" in str(e):
        run("pip install -e '.[bedrock]'")

Prevention

Install the [bedrock] extra whenever configuring AWS models.
Verify installs land in the venv Hermes runs from.

When it happens

Trigger: Configuring provider 'bedrock' (model.provider or auxiliary provider) without boto3 installed (agent/bedrock_adapter.py:69).

Common situations: Base install without the bedrock extra; new machine/container; system Python vs venv mismatch hiding the package.

Related errors

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/300662ee07d37a83. Report an issue: GitHub.