GoogleContainerTools/jib · error · CredentialHelperNotFoundException

The credential helper ${credentialHelper} was not found (No

Error message

The credential helper ${credentialHelper} was not found (No such file or directory)

What it means

CredentialHelperNotFoundException is thrown when the configured credential helper executable does not exist: the underlying process launch failed with 'No such file or directory', 'cannot find the file', or errno=2. Jib detects this specific failure mode and reports that the helper binary itself is missing.

Source

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

          return Credential.from(dockerCredentials.username, dockerCredentials.secret);

        } catch (JsonProcessingException ex) {
          throw new CredentialHelperUnhandledServerUrlException(
              credentialHelper, serverUrl, output);
        }
      }

    } catch (IOException ex) {
      if (ex.getMessage() == null) {
        throw ex;
      }

      // Checks if the failure is due to a nonexistent credential helper CLI.
      if (ex.getMessage().contains("No such file or directory")
          || ex.getMessage().contains("cannot find the file")
          || ex.getMessage().contains("error=2")) /* errno=2 (ENOENT) */ {
        throw new CredentialHelperNotFoundException(credentialHelper, ex);
      }

      throw ex;
    }
  }

  Path getCredentialHelper() {
    return credentialHelper;
  }
}

View on GitHub (pinned to fb949e2676)

Solutions

Install the required helper (e.g. docker-credential-gcr, docker-credential-ecr-login) and ensure it is on PATH.
Remove the helper entry from ~/.docker/config.json (credsStore/credHelpers) if you don't need it.
Provide credentials directly in the build configuration instead of relying on the helper.
Verify PATH in the build environment (CI images often differ from your shell).

Example fix

// before
{ "credHelpers": { "gcr.io": "gcr" } } // binary not installed
// after
brew install docker-credential-gcr  # or remove the credHelpers entry
docker-credential-gcr configure-docker

Defensive patterns

Strategy: validation

Validate before calling

// Check helper exists on PATH before build
boolean found = java.util.stream.Stream.of(System.getenv("PATH").split(java.io.File.pathSeparator))
    .map(dir -> Path.of(dir, "docker-credential-gcr")).anyMatch(java.nio.file.Files::exists);

Try / catch

try { retrieve(); } catch (CredentialHelperNotFoundException e) { logger.error("Helper {} not found: install it or remove from config", e.getCredentialHelper()); }

Prevention

Install required credential helpers in all build environments/CI images.
Keep helper binaries on PATH (check PATH in CI vs local shell).
Remove unused credsStore/credHelpers entries from ~/.docker/config.json.
Prefer explicit auth config where helpers are unavailable.

When it happens

Trigger: docker-credential-<suffix> binary is not on PATH; configured helper name in credHelpers/credsStore does not correspond to any installed binary; PATH differs in CI container.

Common situations: Using docker-credential-gcr on a machine where it was never installed; referencing osxkeychain helper on Linux; slim CI images lacking docker-credential-helpers; PATH not including ~/bin or /usr/local/bin in CI.

Related errors

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