GoogleContainerTools/jib · error · BuildStepsExecutionException

${helpfulSuggestions.forUnknownHost()}

Error message

${helpfulSuggestions.forUnknownHost()}

What it means

BuildStepsExecutionException wrapping a RegistryUnauthorizedException raised in JibBuildRunner.runBuild() when the registry (Docker Hub, GCR, etc.) rejects the push/pull with 401/403 during a container-image build. It fires when credentials are missing, expired, or lack permission for the target repository; the message comes from helpfulSuggestions.forUnknownHost()/credentials guidance, meaning the build was aborted before image layers were shipped.

Source

Thrown at jib-plugins-common/src/main/java/com/google/cloud/tools/jib/plugins/common/JibBuildRunner.java:273

    } catch (RegistryUnauthorizedException ex) {
      handleRegistryUnauthorizedException(ex, helpfulSuggestions);

    } catch (RegistryCredentialsNotSentException ex) {
      throw new BuildStepsExecutionException(helpfulSuggestions.forCredentialsNotSent(), ex);

    } catch (RegistryAuthenticationFailedException ex) {
      if (ex.getCause() instanceof ResponseException) {
        handleRegistryUnauthorizedException(
            new RegistryUnauthorizedException(
                ex.getServerUrl(), ex.getImageName(), (ResponseException) ex.getCause()),
            helpfulSuggestions);
      } else {
        // Unknown cause
        throw new BuildStepsExecutionException(helpfulSuggestions.none(), ex);
      }

    } catch (UnknownHostException ex) {
      throw new BuildStepsExecutionException(helpfulSuggestions.forUnknownHost(), ex);

    } catch (InsecureRegistryException ex) {
      throw new BuildStepsExecutionException(helpfulSuggestions.forInsecureRegistry(), ex);

    } catch (RegistryException ex) {
      String message = Verify.verifyNotNull(ex.getMessage()); // keep null-away happy
      throw new BuildStepsExecutionException(message, ex);

    } catch (ExecutionException ex) {
      String message = ex.getCause().getMessage();
      throw new BuildStepsExecutionException(
          message == null ? "(null exception message)" : message, ex.getCause());

    } catch (InterruptedException ex) {
      Thread.currentThread().interrupt();
      throw new BuildStepsExecutionException(helpfulSuggestions.none(), ex);
    }

View on GitHub (pinned to fb949e2676)

Solutions

1. Run 'docker login' or 'gcloud auth login' / configure credentials with the Jib auth plugins or -Djib.to.auth.username/-Djib.to.auth.password
2. Verify the image reference (registry/repository path) is correct and that the account has push/pull permission
3. For CI, supply credentials via the plugin's auth configuration or a credential helper (gcloud, docker-credential-*)

When it happens

Trigger: Thrown at jib-plugins-common/src/main/java/com/google/cloud/tools/jib/plugins/common/JibBuildRunner.java:273 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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