langchain-ai/deepagents · error · ValueError

a provider already serves rank {provider.rank}

Error message

a provider already serves rank {provider.rank}

What it means

ConfigResolver.install_provider enforces that every ConfigProvider occupies a unique rank in the tier ordering. Installing a provider whose `rank` is already claimed by an existing provider raises ValueError rather than silently replacing or shuffling the existing tier, so resolution precedence stays deterministic.

Source

Thrown at libs/code/deepagents_code/configuration/resolver.py:356

        Used for the CLI tier, which exists only after `argparse` runs — long
        after this resolver may have been built and cached. Unlike
        `reload_with_replacements`, this advances no generation and touches no
        files: the CLI provider is in-memory, so there is nothing to reload,
        and re-arming source diagnostics for an install that invalidates no
        snapshot would only risk a duplicate warning on the next resolution.

        Args:
            provider: Provider to insert. Its rank must not already be present.

        Raises:
            ValueError: If a provider already serves the new provider's rank.
        """
        with self._lock:
            ranks = {existing.rank for existing in self._providers}
            if provider.rank in ranks:
                msg = f"a provider already serves rank {provider.rank}"
                raise ValueError(msg)
            self._providers = tuple(
                sorted((*self._providers, provider), key=lambda p: p.rank)
            )

    def toml_snapshot(self, rank: int) -> TomlSnapshot | None:
        """Return the cached TOML snapshot at `rank`, if that provider is one.

        Lets a caller build a one-off resolver against the same file
        generation this resolver is serving -- for example, re-resolving an
        option with the managed tier masked while keeping the shared user
        snapshot instead of re-parsing `config.toml` off disk.

        Propagates the `RuntimeError` `current_snapshot` raises when the
        provider at `rank` produced no snapshot.

        Args:
            rank: Precedence rank whose snapshot to return.

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pick an unused rank for the new provider before installing.
2. To replace an existing tier, use `resolver.reload_with_replacements({rank: new_provider})` instead of install_provider.
3. If a CLI provider already exists, reuse the cached resolver instead of installing again (get_config_resolver handles caching).

Example fix

// before
resolver.install_provider(TomlFileProvider(name="x", path=p, rank=MANAGED_RANK))
// ValueError: a provider already serves rank MANAGED_RANK
// after: replace the tier instead of adding
resolver.reload_with_replacements({MANAGED_RANK: new_provider})

def can_install(resolver, provider) -> bool:
    return provider.rank not in {p.rank for p in resolver._providers}

if not can_install(resolver, new_provider):
    resolver.reload_with_replacements({new_provider.rank: new_provider})
else:
    resolver.install_provider(new_provider)

try:
    resolver.install_provider(provider)
except ValueError as exc:
    if "already serves rank" in str(exc):
        resolver.reload_with_replacements({provider.rank: provider})  # replace, don't add
    else:
        raise

When it happens

Trigger: Calling `resolver.install_provider(provider)` (directly or via the public helpers `_resolver_with_reload_overrides` / `install_cli_provider`) when `provider.rank` equals the rank of any provider already registered — e.g. installing a second TOML provider at MANAGED_RANK or a second CLI provider at CLI_RANK on one resolver.

Common situations: Test setup installing two fixtures at the same rank; double-initialization installing a CLI provider twice into the same resolver; plugin/config code constructing replacement providers without reusing the replacement API (`reload_with_replacements`) intended for rank reuse.

Related errors

• a different CLI provider is already installed for this proce
• managed_snapshot is a different generation than the one in f
• shared config resolver has no managed TOML provider
• {what} must be absolute: {path}
• Could not determine the home directory: set $HOME, or set DE

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/2e303f2f9a95c98e. Report an issue: GitHub.