GoogleContainerTools/jib · error · CredentialHelperUnhandledServerUrlException

The credential helper ${credentialHelper} returned no creden

Error message

The credential helper ${credentialHelper} returned no credentials for server URL ${serverUrl}; output: ${output}

What it means

CredentialHelperUnhandledServerUrlException is thrown when a Docker credential helper (e.g. docker-credential-gcr) reports 'credentials not found in native keychain' for the given server URL, meaning the helper ran but has no stored credentials for that registry. Jib translates that helper output into this error.

Source

Thrown at jib-core/src/main/java/com/google/cloud/tools/jib/registry/credentials/DockerCredentialHelper.java:170

  private Credential retrieve(List<String> credentialHelperCommand)
      throws IOException, CredentialHelperUnhandledServerUrlException,
          CredentialHelperNotFoundException {
    try {
      ProcessBuilder processBuilder = processBuilderFactory.apply(credentialHelperCommand);
      processBuilder.environment().putAll(environment);
      Process process = processBuilder.start();

      try (OutputStream processStdin = process.getOutputStream()) {
        processStdin.write(serverUrl.getBytes(StandardCharsets.UTF_8));
      }

      try (InputStreamReader processStdoutReader =
          new InputStreamReader(process.getInputStream(), StandardCharsets.UTF_8)) {
        String output = CharStreams.toString(processStdoutReader);

        // Throws an exception if the credential store does not have credentials for serverUrl.
        if (output.contains("credentials not found in native keychain")) {
          throw new CredentialHelperUnhandledServerUrlException(
              credentialHelper, serverUrl, output);
        }
        if (output.isEmpty()) {
          try (InputStreamReader processStderrReader =
              new InputStreamReader(process.getErrorStream(), StandardCharsets.UTF_8)) {
            String errorOutput = CharStreams.toString(processStderrReader);
            throw new CredentialHelperUnhandledServerUrlException(
                credentialHelper, serverUrl, errorOutput);
          }
        }

        try {
          DockerCredentialsTemplate dockerCredentials =
              JsonTemplateMapper.readJson(output, DockerCredentialsTemplate.class);
          if (Strings.isNullOrEmpty(dockerCredentials.username)
              || Strings.isNullOrEmpty(dockerCredentials.secret)) {
            throw new CredentialHelperUnhandledServerUrlException(
                credentialHelper, serverUrl, output);

View on GitHub (pinned to fb949e2676)

Solutions

Run 'docker login <serverUrl>' so the helper/credential store has an entry for that exact server URL.
Ensure the correct credential helper for that registry is configured (e.g. credHelpers in ~/.docker/config.json for gcr.io).
Pass credentials directly in the build config (auth.username/auth.password or credSupplier) instead of relying on the helper.
Verify the server URL string matches what the helper keys credentials under (host:port, scheme stripped).

Example fix

// before: helper has no entry
gcloud auth configure-docker // adds gcr.io helper config
// after
docker login gcr.io   # or gcloud auth login + configure-docker

Defensive patterns

Strategy: try-catch

Validate before calling

// Check helper has credentials before build
Process p = new ProcessBuilder("docker-credential-gcr", "list").start();
String out = new String(p.getInputStream().readAllBytes());
boolean ok = out.contains(serverUrl);

Try / catch

try { cred = DockerCredentialHelper.retrieve(serverUrl, helper); } catch (CredentialHelperUnhandledServerUrlException e) { logger.warn("No creds for {} via {}; run 'docker login {}'", serverUrl, helper, serverUrl); }

Prevention

Run 'docker login <serverUrl>' for every registry used.
Ensure the registry URL string matches the helper's key exactly.
Configure credHelpers per registry in ~/.docker/config.json.
Fall back to explicit auth config in CI.

When it happens

Trigger: Running `retrieve` on DockerCredentialHelper for a serverUrl the helper has no entry for; helper stdout contains 'credentials not found in native keychain'.

Common situations: docker login was never performed for that registry on this machine; helper configured for one registry (e.g. gcr.io) but image targets another (e.g. asia.gcr.io); credentials removed from keychain.

Related errors

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