Document MacOs Homebrew Cli Plugin Location Issue

[cachescrubber]

Document MacOs Homebrew Cli Plugin Location Issue

I just stumbled upon #1678: The documented workaround (from #1678) fixes multi platform buildx configurations for me.

Summary

Plugin execution failed because docker --config points to a temporary directory without a proper config.json. cliPluginsExtraDirs, if configured as documented by Homebrew, has no effect.

Non-Root / Admin solution

cd ~/.docker 
ln -sfn /opt/homebrew/lib/docker/cli-plugins

System Wide (root/admin access necessary)

sudo mkdir -p /usr/local/lib/docker
sudo ln -sfn /opt/homebrew/lib/docker/cli-plugins /usr/local/lib/docker/cli-plugins

It would be good to document this as a known issue or - even better - find the root cause and fix it. I'm unsure if it is docker buildx, homebrew or here. Any help appreciated, I would happily report the issue upstream as well.

Affected Versions

• Docker Maven Plugin version 0.48.0
• macOS Tahoe 26.2 (25C56)
• Docker 29.1.3
• docker buildx: github.com/docker/buildx v0.30.1 Homebrew
• ~/.docker/config.json is configured according to Hombrew caveat.

Client: Docker Engine - Community
 Version:           29.1.3
 API version:       1.52
 Go version:        go1.25.5
 Git commit:        f52814d454
 Built:             Fri Dec 12 14:45:37 2025
 OS/Arch:           darwin/arm64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          29.1.3
  API version:      1.52 (minimum version 1.44)
  Go version:       go1.25.5
  Git commit:       fbf3ed2
  Built:            Fri Dec 12 14:50:13 2025
  OS/Arch:          linux/arm64
  Experimental:     false
 containerd:
  Version:          v2.2.1
  GitCommit:        dea7da592f5d1d2b7755e3a161be07f43fad8f75
 runc:
  Version:          1.3.4
  GitCommit:        v1.3.4-0-gd6d73eb8
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

% brew info docker-buildx
==> docker-buildx: stable 0.30.1 (bottled), HEAD
Docker CLI plugin for extended build capabilities with BuildKit
https://docs.docker.com/buildx/working-with-buildx/
Installed
/opt/homebrew/Cellar/docker-buildx/0.30.1 (41 files, 69.2MB) *
  Poured from bottle using the formulae.brew.sh API on 2025-11-28 at 09:16:02
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/d/docker-buildx.rb
License: Apache-2.0
==> Dependencies
Build: go ✘
==> Options
--HEAD
Install HEAD version
==> Caveats
docker-buildx is a Docker plugin. For Docker to find the plugin, add "cliPluginsExtraDirs" to ~/.docker/config.json:
  "cliPluginsExtraDirs": [
      "/opt/homebrew/lib/docker/cli-plugins"
  ]
==> Analytics
install: 3,249 (30 days), 14,315 (90 days), 67,386 (365 days)
install-on-request: 3,244 (30 days), 14,303 (90 days), 67,309 (365 days)
build-error: 0 (30 days)