lancedb/lancedb · error · ValueError

api_key is required to connect to LanceDB cloud

Error message

api_key is required to connect to LanceDB cloud: {uri}

What it means

A db:// URI indicates LanceDB Cloud, which requires an api_key for authentication. If no api_key argument is supplied and the LANCEDB_API_KEY environment variable is unset, connect() raises this ValueError naming the URI.

Solutions

1. Export the LANCEDB_API_KEY environment variable before connecting
2. Pass api_key='...' explicitly to lancedb.connect
3. Fix the env var name/scope if you believed it was set (e.g. check with os.environ.get('LANCEDB_API_KEY'))

Example fix

// before
conn = lancedb.connect("db://my-db", region="us-east-1")
// after
import os
conn = lancedb.connect(
    "db://my-db",
    api_key=os.environ["LANCEDB_API_KEY"],
    region="us-east-1",
)

import os
if uri.startswith("db://") and not (api_key or os.environ.get("LANCEDB_API_KEY")):
    raise ValueError("LANCEDB_API_KEY must be set for db:// (cloud) connections")

def has_cloud_credentials(uri, api_key=None) -> bool:
    import os
    return not uri.startswith("db://") or bool(api_key or os.environ.get("LANCEDB_API_KEY"))

try:
    conn = lancedb.connect(uri, api_key=api_key, region=region)
except ValueError as e:
    if e.args[0].startswith("api_key is required"):
        api_key = load_api_key_from_secret_store()
        conn = lancedb.connect(uri, api_key=api_key, region=region)
    else:
        raise

When it happens

Trigger: Calling lancedb.connect('db://...') with api_key=None and no LANCEDB_API_KEY env var set.

Common situations: CI/CD or container environments missing the exported LANCEDB_API_KEY; connecting from a fresh machine where credentials were never configured; typos in the env var name so the lookup returns None.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

• Please set the _API_KEY environment variable.
• to_arrow() is not yet supported on LanceDB cloud.
• to_pandas() is not yet supported on LanceDB cloud.
• WATSONX_API_KEY not set. Either set it in your environment…
• a Function environment is pip or conda, not both

AI-assisted analysis of lancedb/lancedb@c7b051aff7 (2026-09-08). Data as JSON: /api/errors/2ef6cd39b3b9ea4e. Report an issue: GitHub.

Appendix: source

Thrown at python/python/lancedb/__init__.py:273

        raise ValueError(
            "namespace_client_impl must be provided when using "
            "namespace_client_properties unless manifest_enabled=True"
        )

    if namespace_client_pushdown_operations is not None:
        raise ValueError(
            "namespace_client_pushdown_operations is only valid when "
            "connecting through a namespace"
        )
    if uri is None:
        raise ValueError(
            "uri is required when not connecting through a namespace client"
        )
    if isinstance(uri, str) and uri.startswith("db://"):
        if api_key is None:
            api_key = os.environ.get("LANCEDB_API_KEY")
        if api_key is None:
            raise ValueError(f"api_key is required to connect to LanceDB cloud: {uri}")
        if isinstance(request_thread_pool, int):
            request_thread_pool = ThreadPoolExecutor(request_thread_pool)
        return RemoteDBConnection(
            uri,
            api_key,
            region,
            host_override,
            sql_host_override=sql_host_override,
            # TODO: remove this (deprecation warning downstream)
            request_thread_pool=request_thread_pool,
            client_config=client_config,
            storage_options=storage_options,
            read_consistency_interval=read_consistency_interval,
            **kwargs,
        )
    _check_s3_bucket_with_dots(str(uri), storage_options)

    if kwargs:

View on GitHub (pinned to c7b051aff7)