langgenius/dify · error · ValueError

Qdrant URL is required.

Error message

Qdrant URL is required.

What it means

ValueError raised in the add-qdrant-index command loop when dify_config.QDRANT_URL is None. The command needs to construct a QdrantConfig for each binding, and without a QDRANT_URL there is no endpoint to connect to. The check is inside the per-binding loop but the value is constant, so it fails on the first binding.

Source

Thrown at api/commands/vector.py:355

@click.option("--field", default="metadata.doc_id", prompt=False, help="Index field , default is metadata.doc_id.")
def add_qdrant_index(field: str):
    click.echo(click.style("Starting Qdrant index creation.", fg="green"))

    create_count = 0

    try:
        bindings = db.session.scalars(select(DatasetCollectionBinding)).all()
        if not bindings:
            click.echo(click.style("No dataset collection bindings found.", fg="red"))
            return
        import qdrant_client
        from dify_vdb_qdrant.qdrant_vector import PathQdrantParams, QdrantConfig
        from qdrant_client.http.exceptions import UnexpectedResponse
        from qdrant_client.http.models import PayloadSchemaType

        for binding in bindings:
            if dify_config.QDRANT_URL is None:
                raise ValueError("Qdrant URL is required.")
            qdrant_config = QdrantConfig(
                endpoint=dify_config.QDRANT_URL,
                api_key=dify_config.QDRANT_API_KEY,
                root_path=current_app.root_path,
                timeout=dify_config.QDRANT_CLIENT_TIMEOUT,
                grpc_port=dify_config.QDRANT_GRPC_PORT,
                prefer_grpc=dify_config.QDRANT_GRPC_ENABLED,
            )
            try:
                params = qdrant_config.to_qdrant_params()
                # Check the type before using
                if isinstance(params, PathQdrantParams):
                    # PathQdrantParams case
                    client = qdrant_client.QdrantClient(path=params.path)
                else:
                    # UrlQdrantParams case - params is UrlQdrantParams
                    client = qdrant_client.QdrantClient(
                        url=params.url,

View on GitHub (pinned to ef8544b173)

Solutions

1. Set QDRANT_URL in the environment or .env (e.g. QDRANT_URL=http://localhost:6333).
2. Confirm the active VectorType is actually Qdrant; if not, this command does not apply.
3. Reload the config after setting the env var (restart the worker/CLI context).
4. Verify with `python -c "from configs import dify_config; print(dify_config.QDRANT_URL)"`.

Example fix

# before
# .env has no QDRANT_URL
flask add-qdrant-index  # raises 'Qdrant URL is required.'

# after
# .env
QDRANT_URL=http://qdrant:6333
QDRANT_API_KEY=
flask add-qdrant-index

from configs import dify_config

def qdrant_configured() -> bool:
    return dify_config.QDRANT_URL is not None

# preflight
if not qdrant_configured():
    raise SystemExit("QDRANT_URL is not set; configure it before running add-qdrant-index")

def qdrant_url_is_set() -> bool:
    return bool(getattr(dify_config, "QDRANT_URL", None))

try:
    run_add_qdrant_index(field)
except ValueError as exc:
    if "Qdrant URL is required" in str(exc):
        click.echo("Set QDRANT_URL in the environment and retry.", err=True)
    raise

When it happens

Trigger: Triggered when running `add-qdrant-index` while the QDRANT_URL environment/config value is unset (None), provided at least one DatasetCollectionBinding exists.

Common situations: The deployment uses a different vector store so QDRANT_URL was never set, the env var was misspelled, or the config was not loaded for the CLI context.

Related errors

• Dataset Collection Binding not found
• Vector store {vector_type} is not supported.
• {label} JSON is invalid: {exc.msg}
• {label} JSON must be an object.
• No tenants found.

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