{"record":{"id":"65ae4cdf12d9b299","repo":"basecamp/kamal","slug":"docker-buildx-plugin-is-not-installed-locally","errorCode":null,"errorMessage":"Docker buildx plugin is not installed locally","messagePattern":"Docker buildx plugin is not installed locally","errorType":"exception","errorClass":"Kamal::Cli::DependencyError","httpStatus":null,"severity":"error","filePath":"lib/kamal/cli/base.rb","lineNumber":319,"sourceCode":"      def with_env(env)\n        current_env = ENV.to_h.dup\n        ENV.update(env)\n        yield\n      ensure\n        ENV.clear\n        ENV.update(current_env)\n      end\n\n      def ensure_docker_installed\n        run_locally do\n          begin\n            execute *KAMAL.builder.ensure_docker_installed\n          rescue SSHKit::Command::Failed => e\n            error = e.message =~ /command not found/ ?\n              \"Docker is not installed locally\" :\n              \"Docker buildx plugin is not installed locally\"\n\n            raise DependencyError, error\n          end\n        end\n      end\n  end\nend\n","sourceCodeStart":301,"sourceCodeEnd":325,"githubUrl":"https://github.com/basecamp/kamal/blob/eee0083b38661c3707c6b6052cc89e85038a096c/lib/kamal/cli/base.rb#L301-L325","documentation":"The same local dependency check as 'Docker is not installed locally', but chosen when the failed message does NOT match /command not found/: the docker binary exists, yet the combined check fails at the buildx stage — meaning the Docker Buildx plugin (needed for multi-platform builds and Kamal's default builder) is missing or broken. Kamal raises Kamal::Cli::DependencyError ('Docker buildx plugin is not installed locally') from ensure_docker_installed before any build runs.","triggerScenarios":"Running `kamal build`/`kamal build push` or `kamal registry login` (without --skip-local) where `docker` works but `docker buildx version` fails: buildx plugin never installed (common on minimal docker-ce installs), plugin directory misconfigured, or an old Docker version bundling no buildx.","commonSituations":"Linux server with docker.io from distro repos (no buildx bundled); Docker installed via snap or a stripped-down package; buildx plugin removed during an upgrade; root-installed plugin not visible to the deploy user.","solutions":["Install the buildx plugin: download the binary from docker/buildx releases to ~/.docker/cli-plugins/docker-buildx (or /usr/local/lib/docker/cli-plugins) and chmod +x it, then verify `docker buildx version`.","Prefer Docker's official repository (docker-ce + docker-buildx-plugin package) over distro packages: `apt-get install docker-buildx-plugin`.","If using Docker Desktop, update it — buildx ships bundled. Verify with `docker buildx ls`.","Confirm the user running kamal can execute the plugin (permissions on the cli-plugins dir)."],"exampleFix":"# before\n$ docker buildx version\ndocker: 'buildx' is not a docker command.\n# after\nmkdir -p ~/.docker/cli-plugins\ncurl -sSL https://github.com/docker/buildx/releases/latest/download/buildx-v0.16.3.linux-amd64 \\\n  -o ~/.docker/cli-plugins/docker-buildx\nchmod +x ~/.docker/cli-plugins/docker-buildx\ndocker buildx version   # now succeeds; kamal build proceeds","handlingStrategy":"validation","validationCode":"abort \"docker buildx missing\" unless system(\"docker buildx version >/dev/null 2>&1\")\nsystem(\"kamal build\")","typeGuard":"def buildx_available?\n  system(\"docker buildx version >/dev/null 2>&1\")\nend","tryCatchPattern":"begin\n  Kamal::CLI::Build.new.invoke(:push)\nrescue Kamal::Cli::DependencyError => e\n  raise unless e.message.include?(\"buildx\")\n  system(\"docker buildx install\") || raise # then retry build\n  retry\nend","preventionTips":["Install docker from Docker's official repos with docker-buildx-plugin in provisioning scripts.","Run `docker buildx ls` as a CI preflight for deploy jobs."],"tags":["kamal","docker","buildx","build","dependency","environment"],"backgroundTag":"docker-buildx-missing","analyzedSha":"eee0083b38661c3707c6b6052cc89e85038a096c","analyzedAt":"2026-08-21T15:17:22.045Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}