python-poetry/poetry · error · PoetryError

At least one source must not be configured as 'explicit'.

Error message

At least one source must not be configured as 'explicit'.

What it means

`PoetryError` from `create_pool` (factory.py:198-201) when every configured source is marked `priority = "explicit"`, leaving the pool with no usable repository. Explicit sources are only consulted when directly named, so resolving any unqualified dependency would be impossible.

Source

Thrown at src/poetry/factory.py:199

            pool.add_repository(repository, priority=priority)
            if repository.name.lower() == "pypi":
                explicit_pypi = True

        # Only add PyPI if no primary repository is configured
        if not explicit_pypi:
            if pool.has_primary_repositories():
                if io.is_debug():
                    io.write_line("Deactivating the PyPI repository")
            else:
                pool.add_repository(
                    cls.create_package_source(
                        {"name": "pypi"}, config, disable_cache=disable_cache
                    ),
                    priority=Priority.PRIMARY,
                )

        if not pool.repositories:
            raise PoetryError(
                "At least one source must not be configured as 'explicit'."
            )

        return pool

    @classmethod
    def create_package_source(
        cls, source: dict[str, str], config: Config, disable_cache: bool = False
    ) -> HTTPRepository:
        from poetry.repositories.exceptions import InvalidSourceError
        from poetry.repositories.legacy_repository import LegacyRepository
        from poetry.repositories.pypi_repository import PyPiRepository
        from poetry.repositories.single_page_repository import SinglePageRepository

        try:
            name = source["name"]
        except KeyError:
            raise InvalidSourceError("Missing [name] in source.")

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Set at least one source to `priority = "primary"` (the default) or `"secondary"`.
2. Remove `priority = "explicit"` from the source you want to serve as default.
3. If PyPI should remain available, do not mark its entry explicit.

Example fix

# before
[[tool.poetry.source]]
name = "pypi"
priority = "explicit"
# after
[[tool.poetry.source]]
name = "pypi"
priority = "primary"

sources = poetry.local_config.get("source", [])
non_explicit = [s for s in sources if s.get("priority", "primary") != "explicit"]
if not non_explicit:
    raise SystemExit("mark at least one source as primary or secondary")

def has_non_explicit_source(sources: list[dict]) -> bool:
    return any(s.get("priority", "primary") != "explicit" for s in sources)

When it happens

Trigger: In pyproject.toml `[[tool.poetry.source]]` all entries set `priority = "explicit"`; PyPI was also re-added as explicit.

Common situations: Locking down to private indexes but accidentally marking the primary one explicit; migrating a config and flipping all sources to explicit.

Related errors

• Missing [name] in source.
• This project requires Poetry {version_constraint}, but you a
• Repository "{name}" does not exist.
• A repository with name {repository_name} was already added.
• RepositoryPool can not remove unknown repository '{name}'.

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/656984f8184c59fb.json. Report an issue: GitHub.