zylon-ai/private-gpt · error · ImportError

Email reader dependencies are not installed.

Error message

Email reader dependencies are not installed.

What it means

Raised as ImportError by _email_reader() in factories/text.py when the lazy import of EmailTextReader fails. As with the delimiter reader, no extras argument is passed to format_missing_dependency_message, so the message carries no install command — email parsing (e.g., the mail libs the reader uses) is considered core, and failure points to a broken or incomplete environment. The underlying ImportError is chained.

Source

Thrown at private_gpt/components/readers/factories/text.py:26

        from private_gpt.components.readers.text.delimiter_reader import (
            DelimiterTextReader,
        )
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message(
                "Delimited text reader",
            )
        ) from e
    return DelimiterTextReader()


def _email_reader() -> IngestionReader:
    try:
        from private_gpt.components.readers.text.email_reader import (
            EmailTextReader,
        )
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message(
                "Email reader",
            )
        ) from e
    return EmailTextReader()


def _html_reader() -> IngestionReader:
    try:
        from private_gpt.components.readers.text.html_reader import (
            HtmlReader,
        )
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message(
                "HTML reader",
                extras="ingest-markup",
            )

View on GitHub (pinned to 4a030776a3)

Solutions

  1. Check e.__cause__ for the precise missing module name.
  2. Re-run uv sync --inexact (with your usual extras) to restore the full dependency set.
  3. Verify the interpreter matches the env (run via the project venv, e.g., .venv/bin/python or uv run).
  4. If a mail-parsing package is individually missing, install it explicitly based on the cause.

Example fix

# repair environment
# uv sync --inexact --extra ingest
# verify import works
# uv run python -c "from private_gpt.components.readers.text.email_reader import EmailTextReader"
Defensive patterns

Strategy: validation

Validate before calling

def email_reader_available() -> bool:
    try:
        from private_gpt.components.readers.text.email_reader import EmailTextReader  # noqa: F401
        return True
    except ImportError:
        return False

if not email_reader_available():
    raise SystemExit("Environment incomplete: re-run uv sync --inexact (with your extras)")

Type guard

def email_reader_available() -> bool:
    try:
        from private_gpt.components.readers.text.email_reader import EmailTextReader  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

try:
    reader = _email_reader()
except ImportError as e:
    logger.error("missing module: %r", e.__cause__ or e)
    raise SystemExit("Repair environment with: uv sync") from e

Prevention

When it happens

Trigger: Ingestion selecting the email sub-reader of the 'text' factory while private_gpt.components.readers.text.email_reader or one of its imports (e.g., a .eml/mail-parsing dependency) cannot be imported in the current interpreter.

Common situations: Broken venv after a partial install or dependency-conflict resolution; running under a different interpreter than the one dependencies were installed to; dependency removed by another tool (pipdeptree/pip uninstall) while pruning; upgrading private-gpt where a new email dependency was added but sync was skipped.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/4ab3fb953237fa8c. Report an issue: GitHub.