langgenius/dify · error · ValueError

ELASTICSEARCH_CLOUD_URL is required when using Elastic Cloud

Error message

ELASTICSEARCH_CLOUD_URL is required when using Elastic Cloud

What it means

Raised by ElasticsearchConfig.validate_elasticsearch_config when ELASTICSEARCH_USE_CLOUD is true but ELASTICSEARCH_CLOUD_URL is empty. Elastic Cloud deployments are addressed by their dedicated endpoint URL rather than host/port.

Source

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

    ELASTICSEARCH_VERIFY_CERTS: bool = Field(
        description="Whether to verify SSL certificates (default is False)", default=False
    )
    ELASTICSEARCH_REQUEST_TIMEOUT: int = Field(
        description="Request timeout in milliseconds (default is 100000)", default=100000
    )
    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

1. Set ELASTICSEARCH_CLOUD_URL to the Elastic Cloud deployment URL (e.g. 'https://xxx.es.region.aws.found.io:443').
2. Set ELASTICSEARCH_API_KEY as well (the next guard requires it).
3. If self-hosted, set ELASTICSEARCH_USE_CLOUD=false (default).

Example fix

// before
ELASTICSEARCH_USE_CLOUD=true
// after
ELASTICSEARCH_USE_CLOUD=true
ELASTICSEARCH_CLOUD_URL=https://xxx.es.region.aws.found.io:443
ELASTICSEARCH_API_KEY=<key>

def es_cloud_ok(use_cloud: bool, cloud_url: str | None, api_key: str | None) -> bool:
    return (not use_cloud) or bool(cloud_url and api_key)

When it happens

Trigger: Setting ELASTICSEARCH_USE_CLOUD=true without ELASTICSEARCH_CLOUD_URL (while selecting elasticsearch as VECTOR_STORE).

Common situations: Switching from self-hosted ES to Elastic Cloud and forgetting the cloud URL, or setting the boolean via one env and the URL via another.

Related errors

• ELASTICSEARCH_API_KEY is required when using Elastic Cloud
• ELASTICSEARCH_HOST is required for self-hosted Elasticsearch
• ELASTICSEARCH_USERNAME is required for self-hosted Elasticse
• ELASTICSEARCH_PASSWORD is required for self-hosted Elasticse
• KNOWLEDGE_FS_BASE_URL and KNOWLEDGE_FS_JWT_SECRET must be co

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