ECONNREFUSED or ERR_CONNECTION_REFUSED means the client reached an address but no service accepted the connection, or a network component actively rejected it. Diagnose the listener and route before changing model or prompt settings.

Verify the destination

Record the exact scheme, hostname, resolved address and port used by the failing process. Then check from the same environment:

getent hosts MODEL_HOST
nc -vz MODEL_HOST MODEL_PORT
curl -v http://MODEL_HOST:MODEL_PORT/health

localhost refers to the current network namespace. Inside a container it is the container itself, not the host and not another service.

Confirm the service is listening

ss -lntp
systemctl status MODEL_SERVICE
docker ps
docker logs MODEL_CONTAINER --tail 200

Check whether the process bound only to 127.0.0.1 when another container or host needs access. Expose the minimum required interface; do not bind an unauthenticated model server publicly as a shortcut.

Containers and service discovery

Use the container-network service name and internal port for container-to-container traffic. Published host ports are for host ingress and may differ.

For Kubernetes:

kubectl get pods,svc,endpoints -n AI_NAMESPACE
kubectl describe pod MODEL_POD -n AI_NAMESPACE
kubectl logs MODEL_POD -n AI_NAMESPACE --previous

A Service with no ready endpoints cannot route to inference. Check readiness, selectors, target ports and rollout state. Use AI Kubernetes troubleshooting for deeper diagnosis.

Deployment causes

• process crashed or failed model startup;
• readiness routed traffic too early;
• wrong environment variable or service name;
• port changed without updating gateway configuration;
• scale-to-zero or cold-start path is not handled;
• firewall or private endpoint rejects the source;
• rollout removed old capacity before new replicas became ready.

Inspect the deployment event and model-server logs. A memory crash may surface first as refused connections; see AI memory troubleshooting.

Retry carefully

A short bounded retry can cover startup or a transient rollout gap, but repeated refused connections will not start a misconfigured service. Use health-aware routing, backoff and a total deadline. Protect state-changing agent work from duplicate execution.

Test local, container and deployed connectivity through AI Testing & Evaluation. Connect service ownership to AI Operations, hosting topology to AI Deployment & Hosting and discovery contracts to AI Application Architecture.