Redis unixsocket "No such file or directory" in CI

By Kaveh Alemi·Latchkey

The client tried to connect over a unix domain socket, but the CI Redis service exposes only TCP over a mapped port. The socket path does not exist in the job filesystem, so the connect fails with "No such file or directory".

What this error means

A client configured with a unixsocket path fails with "Error 2 connecting to unix socket: /var/run/redis/redis.sock. No such file or directory." while TCP on localhost:6379 works.

Could not connect to Redis at /var/run/redis/redis.sock:
No such file or directory

Common causes

Service exposes TCP, client expects a socket

A service container maps a TCP port to the runner host; the unix socket lives inside the container and is not visible to the job, so a socket path connect fails.

Config carried over from a local dev setup

Local development often uses a unix socket path; the same config reused in CI has no matching socket file.

How to fix it

Connect over TCP in CI

1. Switch the client from the unixsocket path to host and port.
2. Read the connection from REDIS_URL so environments can differ.
3. Confirm with a TCP PING.

env:
  REDIS_URL: redis://localhost:6379   # TCP, not a unix socket

Verify TCP reachability

Ping over TCP to confirm the service is up before tests, since the socket path will not exist.

redis-cli -h localhost -p 6379 ping

How to prevent it

• Use TCP (host/port) for Redis in CI, not a unix socket path.
• Externalize the connection via REDIS_URL for env differences.
• Do not reuse a local socket-based config in the pipeline.

Frequently asked questions

Related guides

References

• GitHub Actions documentation