langgenius/dify · error · ValueError

IRIS_MIN_CONNECTION must be less than or equal to IRIS_MAX_C

Error message

IRIS_MIN_CONNECTION must be less than or equal to IRIS_MAX_CONNECTION

What it means

Raised by IrisVectorConfig.validate_config (before-model validator) when IRIS_MIN_CONNECTION > IRIS_MAX_CONNECTION. The connection pool cannot satisfy a floor higher than its ceiling, so the validator rejects it at config load.

Source

Thrown at api/configs/middleware/vdb/iris_config.py:91

            values: Configuration dictionary

        Returns:
            Validated configuration dictionary

        Raises:
            ValueError: If required fields are missing or pool settings are invalid
        """
        # Only validate required fields if IRIS is being used as the vector store
        # This allows the config to be loaded even when IRIS is not in use

        # vector_store = os.environ.get("VECTOR_STORE", "")
        # We rely on Pydantic defaults for required fields if they are missing from env.
        # Strict existence check is removed to allow defaults to work.

        min_conn = values.get("IRIS_MIN_CONNECTION", 1)
        max_conn = values.get("IRIS_MAX_CONNECTION", 3)
        if min_conn > max_conn:
            raise ValueError("IRIS_MIN_CONNECTION must be less than or equal to IRIS_MAX_CONNECTION")

        return values

View on GitHub (pinned to ef8544b173)

Solutions

Ensure IRIS_MIN_CONNECTION <= IRIS_MAX_CONNECTION (defaults 1 and 3).
If you need a bigger floor, raise IRIS_MAX_CONNECTION at least as high.
Re-check the env ordering; both must be PositiveInt.

Example fix

// before
IRIS_MIN_CONNECTION=10
IRIS_MAX_CONNECTION=5
// after
IRIS_MIN_CONNECTION=5
IRIS_MAX_CONNECTION=10

Defensive patterns

Strategy: validation

Validate before calling

def iris_pool_ok(min_conn: int, max_conn: int) -> bool:
    return min_conn <= max_conn and min_conn > 0 and max_conn > 0

Prevention

Always pair IRIS_MIN_CONNECTION with a >= IRIS_MAX_CONNECTION.
Use pool sizing formulas (min = expected steady, max = burst).
Lint both vars together in CI.

When it happens

Trigger: Setting IRIS_MIN_CONNECTION=10 and IRIS_MAX_CONNECTION=5 (in env or values dict).

Common situations: Tuning pool sizing and swapping min/max, or copy-pasting numbers in the wrong order.

Related errors

AI-assisted analysis of langgenius/dify@ef8544b173 (2026-08-12). Data as JSON: /api/errors/c8518d61f9e04154. Report an issue: GitHub.