Python client v3 to v4 migration, which connection API to choose?

Hello, preciously I setup an Weaviate cluster (on AWS), e.g. accessible via

when migrating v3 to v4, which proper connection method I should choose?

Previously for v3, the following method works properly

def get_weaviate_client_v3() -> weaviate.Client:
    cfg = OmegaConf.load(CONFIG_PATH)

    auth_client_secret = hydra.utils.instantiate(cfg.weaviate_client_cfg.auth_client_secret)
    return weaviate.Client(
        timeout_config=(10, 300),

but for V4, where I choose connect_to_local()

def get_weaviate_client_v4():

    cfg = OmegaConf.load(CONFIG_PATH)
    auth_client_secret = weaviate.classes.init.Auth.api_key(cfg.weaviate_client_cfg.auth_client_secret.api_key)

    return weaviate.connect_to_local(

But this v4 connection abovr would throw the following error:

“/opt/homebrew/Cellar/python@3.11/3.11.6_1/Frameworks/Python.framework/Versions/3.11/lib/python3.11/”, line 962, in getaddrinfo
for res in _socket.getaddrinfo(host, port, family, type, proto, flags):
socket.gaierror: [Errno 8] nodename nor servname provided, or not known

File “/Users/tao.feng/projects/weaviate-pilot/src/”, line 55, in get_weaviate_client_v4
return weaviate.connect_to_local(
File “/Users/tao.feng/projects/py311/lib/python3.11/site-packages/weaviate/connect/”, line 157, in connect_to_local
return __connect(client)
File “/Users/tao.feng/projects/py311/lib/python3.11/site-packages/weaviate/connect/”, line 345, in __connect
raise e
File “/Users/tao.feng/projects/py311/lib/python3.11/site-packages/weaviate/connect/”, line 341, in __connect
File “/Users/tao.feng/projects/py311/lib/python3.11/site-packages/weaviate/”, line 282, in connect
File “/Users/tao.feng/projects/py311/lib/python3.11/site-packages/weaviate/connect/”, line 655, in connect
File “/Users/tao.feng/projects/py311/lib/python3.11/site-packages/weaviate/connect/”, line 143, in connect
raise WeaviateStartUpError(f"Could not connect to Weaviate:{e}.") from e
weaviate.exceptions.WeaviateStartUpError: Could not connect to Weaviate:Connection to Weaviate failed. .

Reading weaviate’s migration document, it requires a port for gRPC is open to Weaviate, but since my weaviate cluster is deployed through helm chart, I assume this should already be handled directly, right?

image source:
image: ‘

Any suggestion on resolving this issue?

Server Setup Information

  • Weaviate Server Version: 1.24.1/helm chart 16.8.4
  • Deployment Method: helm chart / K8s
  • Multi Node? Number of Running Nodes: 2
  • Client Language and Version: Python 3.10 / weaviate-client 4.5.1

hi @fairymane !

If you deployed using our helm chart, you need to explicitly enable the grpc service:

when you enable it, you will see also the grpc service in k8s

Let me know if this helps :slight_smile:

Thanks @DudaNogueira for the hint!
Now I override and enabled grpcService in my project values.yaml:

# Set this to true in order to deploy Weaviate gRPC service
enabled: true

And below is the manifest file from the weaviate cluster side:

apiVersion: v1
kind: Service
annotations: ‘sst-weaviate:/Service:sst-weaviate/weaviate-grpc’ >
creationTimestamp: ‘2024-03-15T17:48:52Z’
labels: Helm weaviate
name: weaviate-grpc
namespace: sst-weaviate
resourceVersion: ‘145458532’
uid: 6f99860c-ea37-4b00-8fe5-6d4d126b0913
externalTrafficPolicy: Cluster
internalTrafficPolicy: Cluster
- IPv4
ipFamilyPolicy: SingleStack
- name: grpc
nodePort: 31397
port: 50051
protocol: TCP
targetPort: 50051
app: weaviate
sessionAffinity: None
type: NodePort
loadBalancer: {}

However, when I try to create the client by calling get_weaviate_client_v4() (code defined above), I still got the same error as put above…

Is there any other trouble shooting method (validating the grpc port and python v4 client) I can try?


You will now need to expose this port accordingly with an ingress.

here is how you can test your GRPC connection directly, without weaviate client:

test a weaviate grpc connection

❯ wget
❯ grpcurl -rpc-header “authorization: Bearer WEAVIATE_APIKEY” -proto health.proto http://WEVIATE_URL:WEAVIATE_GRPC_PORT
“status”: “SERVING”