hashicorp/nomad · error

unable to remove existing unix socket for Consul gRPC endpoi

Error message

unable to remove existing unix socket for Consul gRPC endpoint: %v

What it means

Before listening on the host unix socket for the Consul gRPC endpoint, the hook removes any pre-existing socket file; os.Remove failed (e.g. permission denied or stale file held elsewhere), so the proxy cannot bind its socket path.

Source

Thrown at client/allocrunner/consul_grpc_sock_hook.go:283

			return fmt.Errorf("unable to parse address template %q: %v", destAddr, err)
		}
		destAddr = ipStr
	}

	socketFile := allocdir.AllocGRPCSocket
	if p.config.Name != structs.ConsulDefaultCluster && p.config.Name != "" {
		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)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check permissions on the alloc dir and existing socket file
2. Remove the stale socket manually as root if needed
3. Check for another process holding/creating the socket path

When it happens

Trigger: Thrown at client/allocrunner/consul_grpc_sock_hook.go:283 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/65ad7c32e7e21fa1. Report an issue: GitHub.