{"record":{"id":"2ef6cd39b3b9ea4e","repo":"lancedb/lancedb","slug":"api-key-is-required-to-connect-to-lancedb-cloud","errorCode":null,"errorMessage":"api_key is required to connect to LanceDB cloud: {uri}","messagePattern":"api_key is required to connect to LanceDB cloud: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/python/lancedb/__init__.py","lineNumber":273,"sourceCode":"        raise ValueError(\n            \"namespace_client_impl must be provided when using \"\n            \"namespace_client_properties unless manifest_enabled=True\"\n        )\n\n    if namespace_client_pushdown_operations is not None:\n        raise ValueError(\n            \"namespace_client_pushdown_operations is only valid when \"\n            \"connecting through a namespace\"\n        )\n    if uri is None:\n        raise ValueError(\n            \"uri is required when not connecting through a namespace client\"\n        )\n    if isinstance(uri, str) and uri.startswith(\"db://\"):\n        if api_key is None:\n            api_key = os.environ.get(\"LANCEDB_API_KEY\")\n        if api_key is None:\n            raise ValueError(f\"api_key is required to connect to LanceDB cloud: {uri}\")\n        if isinstance(request_thread_pool, int):\n            request_thread_pool = ThreadPoolExecutor(request_thread_pool)\n        return RemoteDBConnection(\n            uri,\n            api_key,\n            region,\n            host_override,\n            sql_host_override=sql_host_override,\n            # TODO: remove this (deprecation warning downstream)\n            request_thread_pool=request_thread_pool,\n            client_config=client_config,\n            storage_options=storage_options,\n            read_consistency_interval=read_consistency_interval,\n            **kwargs,\n        )\n    _check_s3_bucket_with_dots(str(uri), storage_options)\n\n    if kwargs:","sourceCodeStart":255,"sourceCodeEnd":291,"githubUrl":"https://github.com/lancedb/lancedb/blob/c7b051aff7039333a3f61b79217246c27676806a/python/python/lancedb/__init__.py#L255-L291","documentation":"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.","triggerScenarios":"Calling lancedb.connect('db://...') with api_key=None and no LANCEDB_API_KEY env var set.","commonSituations":"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.","solutions":["Export the LANCEDB_API_KEY environment variable before connecting","Pass api_key='...' explicitly to lancedb.connect","Fix the env var name/scope if you believed it was set (e.g. check with os.environ.get('LANCEDB_API_KEY'))"],"exampleFix":"// before\nconn = lancedb.connect(\"db://my-db\", region=\"us-east-1\")\n// after\nimport os\nconn = lancedb.connect(\n    \"db://my-db\",\n    api_key=os.environ[\"LANCEDB_API_KEY\"],\n    region=\"us-east-1\",\n)","handlingStrategy":"validation","validationCode":"import os\nif uri.startswith(\"db://\") and not (api_key or os.environ.get(\"LANCEDB_API_KEY\")):\n    raise ValueError(\"LANCEDB_API_KEY must be set for db:// (cloud) connections\")","typeGuard":"def has_cloud_credentials(uri, api_key=None) -> bool:\n    import os\n    return not uri.startswith(\"db://\") or bool(api_key or os.environ.get(\"LANCEDB_API_KEY\"))","tryCatchPattern":"try:\n    conn = lancedb.connect(uri, api_key=api_key, region=region)\nexcept ValueError as e:\n    if e.args[0].startswith(\"api_key is required\"):\n        api_key = load_api_key_from_secret_store()\n        conn = lancedb.connect(uri, api_key=api_key, region=region)\n    else:\n        raise","preventionTips":["Always source the api key from a secret manager or env var at startup","Add a startup health check that verifies LANCEDB_API_KEY presence","Never hardcode api keys; pass them explicitly in tests via fixtures"],"tags":["python","authentication","cloud"],"backgroundTag":"missing-api-key","analyzedSha":"c7b051aff7039333a3f61b79217246c27676806a","analyzedAt":"2026-09-08T23:42:37.579Z","contentChangedAt":"2026-09-08T23:42:37.579Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}