hashicorp/nomad · error

unable to set permissions on unix socket for Consul gRPC end

Error message

unable to set permissions on unix socket for Consul gRPC endpoint: %v

What it means

After creating the unix socket, Nomad chmods it so unprivileged task users can connect (unix does not allow setting permissions at bind time); the chmod call failed, so the socket exists but would be unusable by tasks, and run aborts.

Source

Thrown at client/allocrunner/consul_grpc_sock_hook.go:299

		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
	return nil
}

// stop the proxy and blocks until the proxy has stopped. Returns an error if
// the proxy does not exit in a timely fashion.
func (p *grpcSocketProxy) stop() error {
	p.cancel()

	// If proxy was never run, don't wait for anything to shutdown.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check ownership/permissions of the socket file and alloc dir
2. Ensure the Nomad client process has rights to chmod within the alloc dir
3. Check for LSM (SELinux/AppArmor) denials in audit logs

When it happens

Trigger: Thrown at client/allocrunner/consul_grpc_sock_hook.go:299 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/9ff824d4caf76c85. Report an issue: GitHub.