GoogleContainerTools/jib · error · BuildStepsExecutionException

${helpfulSuggestions.forNoCredentialsDefined(registryUnautho

Error message

${helpfulSuggestions.forNoCredentialsDefined(registryUnauthorizedException.getImageReference())}

What it means

For a registry 401 (or any non-403 unauthorized response), handleRegistryUnauthorizedException throws a BuildStepsExecutionException with HelpfulSuggestions.forNoCredentialsDefined(imageReference). Jib could not find usable credentials for the registry and the registry rejected the (un)authenticated request.

Source

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

        helpfulSuggestions,
        String.format(STARTUP_MESSAGE_FORMAT_FOR_TARBALL, outputPath.toString()),
        String.format(SUCCESS_MESSAGE_FORMAT_FOR_TARBALL, outputPath.toString()));
  }

  private static void handleRegistryUnauthorizedException(
      RegistryUnauthorizedException registryUnauthorizedException,
      HelpfulSuggestions helpfulSuggestions)
      throws BuildStepsExecutionException {
    if (registryUnauthorizedException.getHttpResponseException().getStatusCode()
        == HttpStatusCodes.STATUS_CODE_FORBIDDEN) {
      // No permissions for registry/repository.
      throw new BuildStepsExecutionException(
          helpfulSuggestions.forHttpStatusCodeForbidden(
              registryUnauthorizedException.getImageReference()),
          registryUnauthorizedException);

    } else {
      throw new BuildStepsExecutionException(
          helpfulSuggestions.forNoCredentialsDefined(
              registryUnauthorizedException.getImageReference()),
          registryUnauthorizedException);
    }
  }

  private final String startupMessage;
  private final String successMessage;
  private final JibContainerBuilder jibContainerBuilder;
  private final Containerizer containerizer;
  private final Consumer<LogEvent> logger;
  private final HelpfulSuggestions helpfulSuggestions;
  @Nullable private Path imageDigestOutputPath;
  @Nullable private Path imageIdOutputPath;
  @Nullable private Path imageJsonOutputPath;

  @VisibleForTesting
  JibBuildRunner(

View on GitHub (pinned to fb949e2676)

Solutions

Run `docker login <registry>` so Jib can pick up credentials from the Docker config.
Or set explicit auth in the build config (jib.to.auth.username/password, or from.auth for pulls).
Or configure a credential helper: `jib.to.credHelper = "ecr-login"` / `gcr` etc.
In CI, pass credentials via environment/system properties (jib.to.auth.username, jib.to.auth.password).

Example fix

// before
jib.to.image = "registry.example.com/app"  // no credentials
// after
jib {
  to {
    image = "registry.example.com/app"
    auth { username = "user"; password = System.getenv("REGISTRY_PASSWORD") }
  }
}

Defensive patterns

Strategy: validation

Validate before calling

// verify credentials resolve before building
// docker config present?
ls ~/.docker/config.json || echo 'run docker login first'

Try / catch

try { jibBuild() } catch (BuildStepsExecutionException e) {
  if (e.getCause() instanceof RegistryUnauthorizedException) {
    // 401: no credentials found — configure auth then retry
  }
}

Prevention

Run `docker login <registry>` before first builds
Configure jib.to.auth/from.auth or a credHelper explicitly in CI
Pass credentials via env/system properties, never hardcode
Ensure CI images include a populated Docker config or helper

When it happens

Trigger: Pushing/pulling to a private registry without any configured credentials — no `to.auth`/`from.auth` config, no docker config.json from `docker login`, and no credential helper found for the registry.

Common situations: First-time pushes to a private registry; CI environments where docker config.json is absent; using a registry different from Docker Hub where no helper is auto-detected.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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