GoogleContainerTools/jib · error · BuildStepsExecutionException

${helpfulSuggestions.forHttpHostConnect()}

Error message

${helpfulSuggestions.forHttpHostConnect()}

What it means

runBuild catches HttpHostConnectException (from Apache HttpClient) and wraps it in a BuildStepsExecutionException with HelpfulSuggestions.forHttpHostConnect(). This means the TCP connection to the registry host could not be established — the registry is unreachable from this machine.

Source

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

      if (imageDigestOutputPath != null) {
        String imageDigest = jibContainer.getDigest().toString();
        Files.write(imageDigestOutputPath, imageDigest.getBytes(StandardCharsets.UTF_8));
      }
      if (imageIdOutputPath != null) {
        String imageId = jibContainer.getImageId().toString();
        Files.write(imageIdOutputPath, imageId.getBytes(StandardCharsets.UTF_8));
      }
      if (imageJsonOutputPath != null) {
        ImageMetadataOutput metadataOutput = ImageMetadataOutput.fromJibContainer(jibContainer);
        String imageJson = metadataOutput.toJson();
        Files.write(imageJsonOutputPath, imageJson.getBytes(StandardCharsets.UTF_8));
      }

      return jibContainer;

    } catch (HttpHostConnectException ex) {
      // Failed to connect to registry.
      throw new BuildStepsExecutionException(helpfulSuggestions.forHttpHostConnect(), ex);

    } 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);
      }

View on GitHub (pinned to fb949e2676)

Solutions

  1. Check the registry hostname/port in the image reference; for a local registry, start it (`docker run -d -p 5000:5000 registry:2`).
  2. Verify connectivity: `curl https://<registry>/v2/` or `docker login <registry>`.
  3. Configure JVM proxy settings (-Dhttps.proxyHost/-Dhttps.proxyPort) if behind a corporate proxy.
  4. Check DNS/firewall/VPN that could block the registry host.

Example fix

// before (local registry not running)
jib.to.image = "localhost:5000/app"
// after: start the registry first
docker run -d -p 5000:5000 --restart=always registry:2
Defensive patterns

Strategy: retry

Validate before calling

// probe the registry before building
if (!curl -fsS https://registry.example.com/v2/ ) echo 'registry unreachable';

Try / catch

try { jibBuild() } catch (BuildStepsExecutionException e) {
  if (e.getCause() instanceof HttpHostConnectException) {
    // transient network issue: retry with backoff after checking connectivity
  }
}

Prevention

When it happens

Trigger: During the build's registry operations, connecting to the registry host fails: wrong registry hostname, registry not running (e.g. local `registry:2` container stopped), firewall/proxy blocking the port, or DNS pointing to a dead host.

Common situations: Local registry container not started; corporate proxy required but not configured; offline/VPN issues; typo in a custom registry hostname; cluster/node network egress blocked.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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