GoogleContainerTools/jib · error · BuildStepsExecutionException

${helpfulSuggestions.forHttpStatusCodeForbidden(registryUnau

Error message

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

What it means

JibBuildRunner.handleRegistryUnauthorizedException converts a 403 Forbidden from a registry into a BuildStepsExecutionException carrying HelpfulSuggestions.forHttpStatusCodeForbidden(imageReference). This means Jib authenticated (or attempted to) but was denied access to the registry or repository — typically because the account lacks push/pull permission for that image path.

Source

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

      HelpfulSuggestions helpfulSuggestions,
      Path outputPath) {
    return new JibBuildRunner(
        jibContainerBuilder,
        containerizer,
        logger,
        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;

View on GitHub (pinned to fb949e2676)

Solutions

Verify the image reference (registry/repository) is spelled correctly and you own/have access to it.
Run `docker login <registry>` with an account that has push/pull rights, or configure jib.to.auth/from.auth explicitly.
For cloud registries, check IAM permissions (e.g. Artifact Registry Writer, ECR push policy) and refresh tokens (`gcloud auth login`, `aws ecr get-login-password`).
Test manually: `docker pull`/`docker push` the same image path to confirm the permission problem is registry-side.

Example fix

// before (403 from wrong namespace)
jib.to.image = "gcr.io/my-project-123/app"
// after (correct project with access)
jib.to.image = "gcr.io/my-actual-project/app"

Defensive patterns

Strategy: try-catch

Try / catch

try { jibBuild() } catch (BuildStepsExecutionException e) {
  if (e.getCause() instanceof RegistryUnauthorizedException
      && ((RegistryUnauthorizedException) e.getCause()).getHttpResponseException().getStatusCode() == 403) {
    // permissions problem on registry/repository — fix IAM or image path
  }
}

Prevention

Verify registry IAM/push permissions before CI builds
Run `docker push` manually once to confirm access
Keep cloud auth fresh (gcloud auth login / aws ecr get-login-password)
Double-check the image repository path and namespace

When it happens

Trigger: During runBuild, the registry returns HTTP 403 for the target image — e.g. pushing to a registry/repository the authenticated user has no write access to, or pulling a private image with a read-only account.

Common situations: Wrong image repository path/namespace; expired or limited-scope service account (GCP, AWS ECR); pushing to an organization you're not a member of; using `docker login` credentials of another user.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

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/ef2b21c87307207c. Report an issue: GitHub.