langgenius/dify · error · ValueError

ELASTICSEARCH_HOST is required for self-hosted Elasticsearch

Error message

ELASTICSEARCH_HOST is required for self-hosted Elasticsearch

What it means

Raised by validate_elasticsearch_config in the self-hosted branch (ELASTICSEARCH_USE_CLOUD false) when ELASTICSEARCH_HOST is empty. The default is '127.0.0.1', so this only fires if an operator explicitly blanks the host.

Source

Thrown at api/configs/middleware/vdb/elasticsearch_config.py:68

    )
    ELASTICSEARCH_RETRY_ON_TIMEOUT: bool = Field(
        description="Whether to retry requests on timeout (default is True)", default=True
    )
    ELASTICSEARCH_MAX_RETRIES: int = Field(
        description="Maximum number of retry attempts (default is 10000)", default=10000
    )

    @model_validator(mode="after")
    def validate_elasticsearch_config(self):
        """Validate Elasticsearch configuration based on deployment type."""
        if self.ELASTICSEARCH_USE_CLOUD:
            if not self.ELASTICSEARCH_CLOUD_URL:
                raise ValueError("ELASTICSEARCH_CLOUD_URL is required when using Elastic Cloud")
            if not self.ELASTICSEARCH_API_KEY:
                raise ValueError("ELASTICSEARCH_API_KEY is required when using Elastic Cloud")
        else:
            if not self.ELASTICSEARCH_HOST:
                raise ValueError("ELASTICSEARCH_HOST is required for self-hosted Elasticsearch")
            if not self.ELASTICSEARCH_USERNAME:
                raise ValueError("ELASTICSEARCH_USERNAME is required for self-hosted Elasticsearch")
            if not self.ELASTICSEARCH_PASSWORD:
                raise ValueError("ELASTICSEARCH_PASSWORD is required for self-hosted Elasticsearch")

        return self

View on GitHub (pinned to ef8544b173)

Solutions

Set ELASTICSEARCH_HOST to the ES hostname/IP (e.g. 'elasticsearch' or '10.0.0.5').
If ES is not used, choose a different VECTOR_STORE so the ES client is never instantiated.
Remove the empty override so the '127.0.0.1' default applies.

Example fix

// before
ELASTICSEARCH_HOST=
// after
ELASTICSEARCH_HOST=elasticsearch

Defensive patterns

Strategy: validation

Validate before calling

def es_host_present(use_cloud: bool, host: str | None) -> bool:
    return use_cloud or bool(host)

Prevention

Do not blank ELASTICSEARCH_HOST; let the default apply if unused.
Choose a non-elasticsearch VECTOR_STORE when ES is not used.
Lint env files for empty overrides of defaulted settings.

When it happens

Trigger: Setting ELASTICSEARCH_HOST='' (empty string) with ELASTICSEARCH_USE_CLOUD unset/false.

Common situations: Unsetting the host expecting the driver to skip ES, or a templated env that renders an empty value.

Related errors

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