hashicorp/nomad · error

unable to create unix socket for Consul gRPC endpoint: %v

Error message

unable to create unix socket for Consul gRPC endpoint: %v

What it means

net.Listen("unix", hostGRPCSocketPath) failed while creating the Consul gRPC unix socket, typically due to permissions on the alloc dir, a path length issue, or filesystem errors; the proxy cannot serve Envoy's gRPC connection.

Source

Thrown at client/allocrunner/consul_grpc_sock_hook.go:290

		socketFile = filepath.Join(allocdir.SharedAllocName, allocdir.TmpDirName,
			"consul_"+p.config.Name+"_grpc.sock")
	}
	hostGRPCSocketPath := filepath.Join(p.allocDir.AllocDirPath(), socketFile)

	// if the socket already exists we'll try to remove it, but if not then any
	// other errors will bubble up to the caller here or when we try to listen
	_, err := os.Stat(hostGRPCSocketPath)
	if err == nil {
		err := os.Remove(hostGRPCSocketPath)
		if err != nil {
			return fmt.Errorf(
				"unable to remove existing unix socket for Consul gRPC endpoint: %v", err)
		}
	}

	listener, err := net.Listen("unix", hostGRPCSocketPath)
	if err != nil {
		return fmt.Errorf("unable to create unix socket for Consul gRPC endpoint: %v", err)
	}

	// The gRPC socket should be usable by all users in case a task is
	// running as an unprivileged user.  Unix does not allow setting domain
	// socket permissions when creating the file, so we must manually call
	// chmod afterwards.
	// https://github.com/golang/go/issues/11822
	if err := os.Chmod(hostGRPCSocketPath, os.ModePerm); err != nil {
		return fmt.Errorf("unable to set permissions on unix socket for Consul gRPC endpoint: %v", err)
	}

	go func() {
		proxy(p.ctx, p.logger, destAddr, listener)
		p.cancel()
		close(p.doneCh)
	}()

	p.runOnce = true

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check alloc dir permissions and free disk space
2. Verify no leftover socket file blocks the bind
3. Confirm the socket path length is within unix socket limits
4. Check filesystem errors in dmesg/client logs

When it happens

Trigger: Thrown at client/allocrunner/consul_grpc_sock_hook.go:290 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/ac04cd6ead942b32. Report an issue: GitHub.