{"record":{"id":"4b4a9fe1e8a019c6","repo":"GoogleContainerTools/jib","slug":"helpfulsuggestions-forhttphostconnect","errorCode":null,"errorMessage":"${helpfulSuggestions.forHttpHostConnect()}","messagePattern":"\\$\\{helpfulSuggestions\\.forHttpHostConnect\\(\\)\\}","errorType":"exception","errorClass":"BuildStepsExecutionException","httpStatus":null,"severity":"error","filePath":"jib-plugins-common/src/main/java/com/google/cloud/tools/jib/plugins/common/JibBuildRunner.java","lineNumber":253,"sourceCode":"      if (imageDigestOutputPath != null) {\n        String imageDigest = jibContainer.getDigest().toString();\n        Files.write(imageDigestOutputPath, imageDigest.getBytes(StandardCharsets.UTF_8));\n      }\n      if (imageIdOutputPath != null) {\n        String imageId = jibContainer.getImageId().toString();\n        Files.write(imageIdOutputPath, imageId.getBytes(StandardCharsets.UTF_8));\n      }\n      if (imageJsonOutputPath != null) {\n        ImageMetadataOutput metadataOutput = ImageMetadataOutput.fromJibContainer(jibContainer);\n        String imageJson = metadataOutput.toJson();\n        Files.write(imageJsonOutputPath, imageJson.getBytes(StandardCharsets.UTF_8));\n      }\n\n      return jibContainer;\n\n    } catch (HttpHostConnectException ex) {\n      // Failed to connect to registry.\n      throw new BuildStepsExecutionException(helpfulSuggestions.forHttpHostConnect(), ex);\n\n    } catch (RegistryUnauthorizedException ex) {\n      handleRegistryUnauthorizedException(ex, helpfulSuggestions);\n\n    } catch (RegistryCredentialsNotSentException ex) {\n      throw new BuildStepsExecutionException(helpfulSuggestions.forCredentialsNotSent(), ex);\n\n    } catch (RegistryAuthenticationFailedException ex) {\n      if (ex.getCause() instanceof ResponseException) {\n        handleRegistryUnauthorizedException(\n            new RegistryUnauthorizedException(\n                ex.getServerUrl(), ex.getImageName(), (ResponseException) ex.getCause()),\n            helpfulSuggestions);\n      } else {\n        // Unknown cause\n        throw new BuildStepsExecutionException(helpfulSuggestions.none(), ex);\n      }\n","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/GoogleContainerTools/jib/blob/fb949e2676afbbd7dd7a1ef61e20251931325654/jib-plugins-common/src/main/java/com/google/cloud/tools/jib/plugins/common/JibBuildRunner.java#L235-L271","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the registry hostname/port in the image reference; for a local registry, start it (`docker run -d -p 5000:5000 registry:2`).","Verify connectivity: `curl https://<registry>/v2/` or `docker login <registry>`.","Configure JVM proxy settings (-Dhttps.proxyHost/-Dhttps.proxyPort) if behind a corporate proxy.","Check DNS/firewall/VPN that could block the registry host."],"exampleFix":"// before (local registry not running)\njib.to.image = \"localhost:5000/app\"\n// after: start the registry first\ndocker run -d -p 5000:5000 --restart=always registry:2","handlingStrategy":"retry","validationCode":"// probe the registry before building\nif (!curl -fsS https://registry.example.com/v2/ ) echo 'registry unreachable';","typeGuard":null,"tryCatchPattern":"try { jibBuild() } catch (BuildStepsExecutionException e) {\n  if (e.getCause() instanceof HttpHostConnectException) {\n    // transient network issue: retry with backoff after checking connectivity\n  }\n}","preventionTips":["Confirm registry host/port and that the registry is running","Configure JVM proxy properties in corporate networks","Health-check the registry (/v2/ endpoint) in CI preflight","Watch DNS/VPN changes that affect the registry hostname"],"tags":["network","docker","registry","connection"],"backgroundTag":"connection-refused","analyzedSha":"fb949e2676afbbd7dd7a1ef61e20251931325654","analyzedAt":"2026-09-06T14:04:09.491Z","contentChangedAt":"2026-09-06T14:04:09.491Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}