{"record":{"id":"742d717347194c68","repo":"basecamp/kamal","slug":"docker-is-not-installed-locally","errorCode":null,"errorMessage":"Docker is not installed locally","messagePattern":"Docker 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":"Before building images or logging into the registry locally (kamal build, kamal registry login), Kamal runs a combined check `docker ... && docker buildx version` on the machine invoking kamal. If that SSHKit command fails with 'command not found' in the message, the docker binary itself is missing from PATH, and Kamal raises Kamal::Cli::DependencyError ('Docker is not installed locally') — distinct from the buildx-plugin variant chosen when docker exists but the plugin check fails.","triggerScenarios":"Running `kamal build` (also `kamal build push`, `kamal registry login` without --skip-local) on a machine where `docker` is not on PATH: no Docker Desktop, docker CLI not installed, or running inside CI/containers where the docker socket/CLI are absent. The ensure_docker_installed helper at lib/kamal/cli/base.rb:310 catches SSHKit::Command::Failed and inspects the message for /command not found/.","commonSituations":"Fresh workstation without Docker Desktop installed; CI image (ruby:3.x) lacking the docker CLI; docker installed via asdf/mise shim not active in the deploy job's PATH; deploying from a server that only has the kamal gem.","solutions":["Install Docker on the machine running kamal (Docker Desktop on macOS/Windows, docker-ce on Linux), then verify with `docker version` (non-root PATH included).","In CI, use an image with the docker CLI or install it in the job before `kamal build` (e.g. apt-get install docker.io or use a docker:dind setup with the CLI available).","If docker is installed but not found, fix PATH so the kamal process can see it (login shell, mise/asdf shims, systemd service Environment).","If you only need remote operations, skip local checks where supported (e.g. `kamal registry login --skip-local`) or run builds where docker exists."],"exampleFix":"# before (CI step)\n- gem install kamal\n- kamal build push   # DependencyError: Docker is not installed locally\n# after\n- gem install kamal\n- apt-get update && apt-get install -y docker.io   # or use an image with docker CLI\n- kamal build push","handlingStrategy":"validation","validationCode":"abort \"docker CLI not available\" if `which docker`.empty?\nsystem(\"kamal build\")","typeGuard":"def docker_available?\n  system(\"docker version >/dev/null 2>&1\")\nend","tryCatchPattern":"begin\n  Kamal::CLI::Build.new.invoke(:push)\nrescue Kamal::Cli::DependencyError => e\n  abort \"install docker CLI on this machine first: #{e.message}\"\nend","preventionTips":["Run kamal builds on machines/CI images with the docker CLI preinstalled (docker:cli or dind setups).","Add a `docker version` preflight step to deploy pipelines."],"tags":["kamal","docker","build","dependency","environment"],"backgroundTag":"docker-not-installed","analyzedSha":"eee0083b38661c3707c6b6052cc89e85038a096c","analyzedAt":"2026-08-21T15:17:22.045Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}