langgenius/dify · error · ValueError

ELASTICSEARCH_API_KEY is required when using Elastic Cloud

Error message

ELASTICSEARCH_API_KEY is required when using Elastic Cloud

What it means

Raised by validate_elasticsearch_config when Elastic Cloud is enabled but ELASTICSEARCH_API_KEY is empty. Elastic Cloud authenticates via API key, not username/password.

Source

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

    )
    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. Generate an API key in the Elastic Cloud console and set ELASTICSEARCH_API_KEY.
2. If you intend self-hosted auth, set ELASTICSEARCH_USE_CLOUD=false and use username/password.

Example fix

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

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

When it happens

Trigger: ELASTICSEARCH_USE_CLOUD=true with ELASTICSEARCH_CLOUD_URL set but ELASTICSEARCH_API_KEY unset.

Common situations: Provisioning cloud URL but deferring API key creation, or assuming username/password carry over to cloud mode.

Related errors

• ELASTICSEARCH_USERNAME is required for self-hosted Elasticse
• ELASTICSEARCH_PASSWORD is required for self-hosted Elasticse
• ELASTICSEARCH_CLOUD_URL is required when using Elastic Cloud
• ELASTICSEARCH_HOST is required for self-hosted Elasticsearch
• KNOWLEDGE_FS_BASE_URL must not include credentials, query, o

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