pymemcache / python-memcached connection failure in CI

By Daniel Zoghalchali·Latchkey

A Python memcached client (pymemcache or python-memcached) failed to connect to a configured server. With a single node it is a readiness or host problem; with a multi-server pooled client, consistent hashing may route a key to a node that is down in CI.

What this error means

Tests fail with "MemcacheUnexpectedCloseError", "Connection refused", or silent misses because a HashClient node is unreachable in CI.

pymemcache.exceptions.MemcacheServerError: (b'localhost:11211',
'Connection refused')

Common causes

Single node not ready or wrong host

The memcached service was not ready, or the host is localhost when the job runs in a container that needs the service name.

A dead node in a consistent-hashing pool

A HashClient distributes keys across servers; if one configured node is not running in CI, keys hashing to it fail.

How to fix it

Connect to a single ready node in CI

1. Point the client at one memcached the workflow actually starts.
2. Wait for the port to open before the first call.
3. Read the host/port from environment so it is portable.

import os
from pymemcache.client.base import Client
c = Client((os.environ.get("MEMCACHED_HOST", "localhost"), 11211))
c.set(b"k", b"v")
assert c.get(b"k") == b"v"

Only configure nodes that exist in CI

If using HashClient, list only the servers the workflow starts so consistent hashing never routes to a missing node.

from pymemcache.client.hash import HashClient
c = HashClient([("localhost", 11211)])

How to prevent it

• Wait for memcached readiness before the first client call.
• Configure only the nodes the workflow actually starts.
• Externalize host/port so tests run against the CI service.

Frequently asked questions

Related guides

References

• GitHub Actions documentation