GoogleContainerTools/jib · error · FileNotFoundException

Specified credential helper was not found: ${credentialHelpe

Error message

Specified credential helper was not found: ${credentialHelper}

What it means

DefaultCredentialRetrievers.asList validates a configured credential helper path when the helper contains a path separator (i.e. an explicit path). If the file does not exist on disk (allowing Windows `.cmd`/`.exe` variants), a FileNotFoundException is thrown naming the helper. This ensures Jib fails fast instead of spawning a nonexistent helper at auth time.

Source

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

   *
   * @return the list of {@link CredentialRetriever}s
   * @throws FileNotFoundException if a credential helper path is specified, but the file doesn't
   *     exist
   */
  public List<CredentialRetriever> asList() throws FileNotFoundException {
    List<CredentialRetriever> credentialRetrievers = new ArrayList<>();
    if (knownCredentialRetriever != null) {
      credentialRetrievers.add(knownCredentialRetriever);
    }
    if (credentialHelper != null) {
      // If credential helper contains file separator, treat as path; otherwise treat as suffix
      if (credentialHelper.contains(FileSystems.getDefault().getSeparator())) {
        if (!Files.exists(Paths.get(credentialHelper))) {
          String osName = systemProperties.getProperty("os.name").toLowerCase(Locale.ENGLISH);
          if (!osName.contains("windows")
              || (!Files.exists(Paths.get(credentialHelper + ".cmd"))
                  && !Files.exists(Paths.get(credentialHelper + ".exe")))) {
            throw new FileNotFoundException(
                "Specified credential helper was not found: " + credentialHelper);
          }
        }
        credentialRetrievers.add(
            credentialRetrieverFactory.dockerCredentialHelper(credentialHelper));
      } else {
        String suffix = credentialHelper; // not path; treat as suffix
        credentialRetrievers.add(
            credentialRetrieverFactory.dockerCredentialHelper("docker-credential-" + suffix));
      }
    }

    if (inferredCredentialRetriever != null) {
      credentialRetrievers.add(inferredCredentialRetriever);
    }

    Set<Path> dockerConfigFiles = new LinkedHashSet<>();

View on GitHub (pinned to fb949e2676)

Solutions

  1. Install the credential helper (e.g. `docker-credential-gcr`, `docker-credential-ecr-login`) or correct the configured path.
  2. Ensure the file is executable and on the expected absolute path.
  3. On Windows, verify `helper.cmd` or `helper.exe` exists next to the configured path.
  4. Alternatively drop the helper config and use `from.auth`/`to.auth` username/password, or a Docker config from a `docker login`.

Example fix

// before
jib.to.credHelper = "/opt/bin/docker-credential-ecr-login"  // file missing
// after
jib.to.credHelper = "ecr-login"  // on PATH, no separator -> no file check
// or install it: docker-credential-ecr-login at the configured path
Defensive patterns

Strategy: validation

Validate before calling

// check helper exists before invoking Jib
import java.nio.file.*;
if (helper.contains(FileSystems.getDefault().getSeparator()) && !Files.exists(Paths.get(helper))) {
  throw new IllegalStateException("credential helper missing: " + helper);
}

Try / catch

try { jibBuild() } catch (BuildStepsExecutionException e)
       /* cause: java.io.FileNotFoundException: Specified credential helper was not found */ {
  // install the helper or switch to a name on PATH / explicit auth
}

Prevention

When it happens

Trigger: Configuring a path-style credential helper, e.g. `jib.to.auth.dockerCredentialHelper=/opt/bin/docker-credential-ecr-login`, where the file is not present (or on Windows, neither `helper.cmd` nor `helper.exe` exists).

Common situations: Docker credential helper not installed (docker-credential-gcr/ecr-login); helper installed under a name/path that differs from config; missing `.exe` extension on Windows; typo in the path.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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