agentscope-ai/agentscope · error · ValueError

AGENTSCOPE_WORKER_BOOTSTRAP must be in 'module:attr' form, g

Error message

AGENTSCOPE_WORKER_BOOTSTRAP must be in 'module:attr' form, got {dotted!r}.

What it means

The RAG index worker entrypoint resolves the AGENTSCOPE_WORKER_BOOTSTRAP env var, which must be a 'module:attr' dotted path (e.g. 'myapp.workers:bootstrap'). If the string contains no colon, _resolve raises ValueError before attempting the import. This is the standard setuptools-style entry-point format.

Source

Thrown at src/agentscope/app/rag/index_worker/__main__.py:71

def _resolve(dotted: str) -> Callable[[], dict[str, Any]]:
    """Import ``module:attribute`` and return the attribute.

    Args:
        dotted (`str`):
            A ``module:attribute`` reference; must contain a colon.

    Returns:
        `Callable[[], dict[str, Any]]`:
            The resolved attribute — expected to be a zero-arg
            callable that returns the kwargs dict for
            :func:`run_worker`.

    Raises:
        `ValueError`:
            When ``dotted`` does not contain a colon.
    """
    if ":" not in dotted:
        raise ValueError(
            f"AGENTSCOPE_WORKER_BOOTSTRAP must be in 'module:attr' "
            f"form, got {dotted!r}.",
        )
    module_name, _, attr = dotted.partition(":")
    module = importlib.import_module(module_name)
    return getattr(module, attr)


def main() -> None:
    """Resolve the bootstrap callable from the environment and run the worker.

    Reads ``AGENTSCOPE_WORKER_BOOTSTRAP`` (``module:attr`` form),
    imports the target, calls it for the kwargs dict, and forwards
    them to :func:`run_worker`.  Exits with code ``2`` when the
    environment variable is missing — the deployment must supply it
    because backend selection is a deployment concern.
    """
    logging.basicConfig(

View on GitHub (pinned to e90f1c7592)

Solutions

1. Set the var in 'module:attr' form: AGENTSCOPE_WORKER_BOOTSTRAP='myapp.workers:bootstrap'
2. Verify with: echo "$AGENTSCOPE_WORKER_BOOTSTRAP" that the colon survived shell/env-file quoting
3. Ensure the target module is importable and the attribute exists (the next step will importlib.import_module it)
4. Document the exact format next to the variable in your deployment manifests

Example fix

# before
ENV AGENTSCOPE_WORKER_BOOTSTRAP=myapp.workers.bootstrap  # ValueError

# after
ENV AGENTSCOPE_WORKER_BOOTSTRAP=myapp.workers:bootstrap

def valid_bootstrap(spec: str) -> bool:
    return ':' in spec and all(part.strip() for part in spec.split(':', 1))

import os
spec = os.environ['AGENTSCOPE_WORKER_BOOTSTRAP']
assert valid_bootstrap(spec), f"must be 'module:attr', got {spec!r}"

null

try:
    bootstrap = _resolve(spec)
except ValueError as e:
    raise SystemExit(f'Bad AGENTSCOPE_WORKER_BOOTSTRAP: {e}') from e

When it happens

Trigger: Running python -m agentscope.app.rag.index_worker with AGENTSCOPE_WORKER_BOOTSTRAP set to 'myapp.workers.bootstrap' (dots instead of colon), 'bootstrap', or empty/whitespace-mangled values.

Common situations: Copy-pasting a Python import path instead of an entry-point spec in docker-compose/k8s env blocks; shell quoting that strips the colon; .env file typos; migrating from a config format that used plain module paths.

Related errors

• Invalid logging level: {level}. Must be one of 'INFO', 'DEBU
• factory must be a callable, got {type(factory).__name__}
• The 'reserve_ratio' of the context config must be smaller th
• The 'context_buffer_ratio' of the injection config must be s
• Channel type '{channel_type}' is not registered; pass it to

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/b3d60ee9635da0fe. Report an issue: GitHub.