GoogleContainerTools/jib · error · GradleException

${HELPFUL_SUGGESTIONS_PREFIX}, perhaps you should make sure

Error message

${HELPFUL_SUGGESTIONS_PREFIX}, perhaps you should make sure Docker is installed and you have correct privileges to run it

What it means

BuildDockerTask (Gradle 'jibBuildDocker') throws a GradleException when the Docker CLI executable cannot be found: either the default docker binary is absent or the configured dockerClient.executable path does not exist. Jib includes HelpfulSuggestions noting you should verify Docker is installed and that you have privileges to run it.

Source

Thrown at jib-gradle-plugin/src/main/java/com/google/cloud/tools/jib/gradle/BuildDockerTask.java:102

   * @throws BuildStepsExecutionException if an error occurs while executing build steps
   * @throws CacheDirectoryCreationException if a new cache directory could not be created
   * @throws MainClassInferenceException if a main class could not be found
   * @throws InvalidGlobalConfigException if the global config file is invalid
   */
  @TaskAction
  public void buildDocker()
      throws IOException, BuildStepsExecutionException, CacheDirectoryCreationException,
          MainClassInferenceException, InvalidGlobalConfigException {
    Preconditions.checkNotNull(jibExtension);

    // Check deprecated parameters
    Path dockerExecutable = jibExtension.getDockerClient().getExecutablePath();
    boolean isDockerInstalled =
        dockerExecutable == null
            ? CliDockerClient.isDefaultDockerInstalled()
            : CliDockerClient.isDockerInstalled(dockerExecutable);
    if (!isDockerInstalled) {
      throw new GradleException(
          HelpfulSuggestions.forDockerNotInstalled(HELPFUL_SUGGESTIONS_PREFIX));
    }

    TaskCommon.disableHttpLogging();
    TempDirectoryProvider tempDirectoryProvider = new TempDirectoryProvider();

    GradleProjectProperties projectProperties =
        GradleProjectProperties.getForProject(
            getProject(),
            getLogger(),
            tempDirectoryProvider,
            jibExtension.getConfigurationName().get());
    GlobalConfig globalConfig = GlobalConfig.readConfig();
    Future<Optional<String>> updateCheckFuture =
        TaskCommon.newUpdateChecker(projectProperties, globalConfig, getLogger());
    try {

      PluginConfigurationProcessor.createJibBuildRunnerForDockerDaemonImage(

View on GitHub (pinned to fb949e2676)

Solutions

1. Install Docker and start the daemon, or point jib.dockerClient.executable to a valid docker binary.
2. Fix the executable path in the build config if custom: jib { dockerClient { executable = '/path/to/docker' } }.
3. If you only wanted to build/push the image without a local Docker daemon, use 'jib build' or 'jibBuildTar' instead of 'jibBuildDocker'.
4. Grant privileges (docker group / run as non-root user in docker group) if Docker is installed but inaccessible.

Example fix

// before
./gradlew jibBuildDocker // docker not installed
// after (no local Docker needed)
./gradlew jibBuild  # or: jib { dockerClient { executable = '/usr/local/bin/docker' } }

// Check docker availability before invoking jibBuildDocker
boolean ok = com.google.cloud.tools.jib.builder.cli.CliDockerClient.isDefaultDockerInstalled();

try { /* ./gradlew jibBuildDocker */ } catch (GradleException e) { if (e.getMessage().contains("Docker is installed")) { logger.lifecycle("Docker missing; falling back to 'jib build'"); } }

When it happens

Trigger: Running ./gradlew jibBuildDocker on a machine without Docker installed; jib.dockerClient.executable set to a wrong path; Docker CLI present but daemon unusable/unprivileged in the environment.

Common situations: CI containers without Docker; building on a machine that never installed Docker Desktop; path to docker binary changed after upgrade; missing group/permission to run docker.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• the configured platform (%s/%s) doesn't match the platform (
• Timeout reached while waiting for 'docker info' output
• Failed to read output of 'docker info': <message>
• 'docker load' command failed with error: + error
• 'docker load' command failed with error: + getStderrOutput(d

AI-assisted analysis of GoogleContainerTools/jib@fb949e2676 (2026-09-06). Data as JSON: /api/errors/171bbcb2f9c36040. Report an issue: GitHub.