Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsSome links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Kaniko executor couldn’t push the image into the container registry is a symptom, not a diagnosis. Start with the innermost error: check that --destination is an image reference without https://, verify that Kaniko can read credentials for the exact registry hostname, and confirm that the identity can upload to the exact repository. Then isolate cache, tag, TLS, and network issues. One important caveat: the official Kaniko repository was archived on June 3, 2025, so persistent compatibility problems may be a reason to plan a move to a maintained builder.
Start with the exact error
Do not treat every push failure as a password problem. A malformed destination, missing credential mount, insufficient repository permission, inaccessible registry, immutable tag, or cache write can all fail near the end of a build. Capture the complete log and classify the innermost error before changing flags.
| Error or symptom | Likely cause | First action |
|---|---|---|
https://https/v2/ or DNS lookup for https |
The destination includes a URL scheme. | Remove https:// from --destination. |
UNAUTHORIZED or 401 |
Credentials are missing, unreadable, expired, or do not match the registry hostname. | Check the credential file, mount, and hostname alignment. |
DENIED or 403 Forbidden |
The identity authenticated but lacks permission for the target repository or project. | Grant the required upload/push permission at the correct scope. |
| Cache push fails while the image push appears valid | The cache repository has a separate path, policy, or permission issue. | Retry with caching disabled, then inspect cache access. |
x509: certificate signed by unknown authority |
Private CA, incomplete chain, hostname mismatch, or TLS-intercepting proxy. | Trust the correct CA in the executor environment. |
lookup registry... no such host, timeout, or connection refused |
DNS, egress, proxy, firewall, network policy, or wrong endpoint. | Test registry reachability from the build pod or runner. |
| Immutable-tag error | The target tag already exists and cannot be overwritten. | Use a unique tag or intentionally handle a safe race. |
MANIFEST_BLOB_UNKNOWN |
Possible registry interaction, upload race, or compatibility issue—not necessarily bad credentials. | Try a unique tag and compare behavior with another OCI client. |
A Kaniko issue documents an UNAUTHORIZED response during push-permission checking, while another shows that reaching a token endpoint does not prove that the principal has Artifact Registry upload permission. See the push-scope example and the Artifact Registry permission example.
Recommended Free Tools
1. Correct the destination reference
Kaniko expects an OCI-style image reference, not a browser URL or registry API endpoint. Use:
#1 Best Overall
registry.example.com/team/app:tagDo not use:
https://registry.example.com/team/app:tag
http://registry.example.com/team/app:tag
registry.example.com/v2/team/app:tagA reported failure with https:// in the destination caused Kaniko to interpret the registry hostname as https and request https://https/v2/, resulting in DNS failure; see the reported case. The same principle applies to registry web pages: a Docker Hub page such as https://hub.docker.com/r/acme/widget is not the image reference. Use docker.io/acme/widget:tag.
Typical destinations look like these:
docker.io/acme/widget:1.4.2ghcr.io/acme/widget:1.4.2registry.gitlab.com/acme/project/widget:1.4.2us-central1-docker.pkg.dev/my-project/my-repository/widget:1.4.2123456789012.dkr.ecr.us-east-1.amazonaws.com/widget:1.4.2myregistry.azurecr.io/widget:1.4.2
Also check for a misspelled host, missing namespace/project/repository segment, uppercase image-name characters, an unset or empty tag variable, or a destination repository different from the one your credentials authorize. A generic invocation is:
/kaniko/executor
--context "$CI_PROJECT_DIR"
--dockerfile "$CI_PROJECT_DIR/Dockerfile"
--destination "registry.example.com/team/app:${IMAGE_TAG}"2. Verify Kaniko can read the credentials
Kaniko commonly reads Docker-format credentials from /kaniko/.docker/config.json. A basic username/password entry uses a base64-encoded username:password value:
{
"auths": {
"registry.example.com": {
"auth": "BASE64_OF_USERNAME_COLON_PASSWORD"
}
}
}In CI, generate the value from protected variables rather than committing a credential:
AUTH="$(printf '%s:%s' "$REGISTRY_USER" "$REGISTRY_PASSWORD" | base64 | tr -d 'n')"
mkdir -p /kaniko/.docker
cat > /kaniko/.docker/config.json <<EOF
{
"auths": {
"${REGISTRY_HOST}": {
"auth": "${AUTH}"
}
}
}
EOFDo not print this file in job logs; it may contain credentials that remain valid beyond the build. Check that it exists without exposing contents:
Rank #2
ls -l /kaniko/.docker
test -s /kaniko/.docker/config.jsonThe hostname under auths must correspond to the hostname used in --destination and expected by the authentication mechanism. Depending on registry and Kaniko version, registry.example.com, https://registry.example.com, and Docker Hub’s historical https://index.docker.io/v1/ entry may not be interchangeable. Kaniko’s README examples document Docker Hub and registry-specific credential approaches; follow the format applicable to your registry and pinned image rather than assuming one format works everywhere.
For Kubernetes, a Docker registry secret can be mounted at Kaniko’s expected path. The secret’s .dockerconfigjson key is exposed in the container as config.json:
apiVersion: v1
kind: Pod
metadata:
name: kaniko
spec:
containers:
- name: kaniko
image: gcr.io/kaniko-project/executor:v1.24.0-debug
args:
- --context=dir:///workspace
- --dockerfile=/workspace/Dockerfile
- --destination=registry.example.com/team/app:latest
volumeMounts:
- name: docker-config
mountPath: /kaniko/.docker
readOnly: true
volumes:
- name: docker-config
secret:
secretName: registry-credentials
items:
- key: .dockerconfigjson
path: config.jsonConfirm the Kubernetes secret type without decoding or displaying its data:
kubectl get secret registry-credentials -o jsonpath='{.type}{"n"}'The expected type is generally kubernetes.io/dockerconfigjson. Check the key name, mount path, namespace, and container that receives the mount. A secret can exist and still be invisible to the executor because it was mounted under a different path or key.
3. Separate authentication from authorization
Authentication answers “who are you?” Authorization answers “may you upload here?” A token can be valid yet lack the ability to create uploads, push blobs or manifests, write cache layers, or access the requested project, account, region, repository, or namespace. If the error is 403 or DENIED, verify the repository path and grant the narrowest suitable push/upload permission. Private base images may also require pull access independent of push access.
Rank #3
Registry-specific checks
- Docker Hub: Use the correct namespace and repository, and use a personal access token where account policy supports or requires it. Confirm the token and account have write access. The Docker Hub web URL is not the registry hostname.
- GitLab Container Registry: The CI identity and token must be allowed to push to the project’s image path. In GitLab CI, a common pattern is to use
CI_REGISTRY,CI_REGISTRY_USER, andCI_REGISTRY_PASSWORDto create the auth entry. Those variable names are GitLab-specific; do not copy them unchanged into another CI system. GitLab also documents private-registry certificate handling in its Kaniko guidance. - Google Artifact Registry: Use the correct regional hostname and an existing repository in the intended project. The workload principal needs a role permitting uploads to that repository, commonly an appropriate Artifact Registry writer role. Do not apply old Google Container Registry (GCR) instructions using broad Storage permissions as universal Artifact Registry guidance; the products and permission models differ.
- Amazon ECR: The executor image includes ECR credential-helper support, but the workload still needs permission to obtain an authorization token and upload layers and manifests. Kaniko’s documentation notes conditional settings such as
AWS_SDK_LOAD_CONFIG=trueand, in some EC2 instance-profile situations,AWS_EC2_METADATA_DISABLED=true; these are not required for every ECR build. - Azure Container Registry: Kaniko documents the
acr-envhelper. Prefer a host-specific entry such as"credHelpers": {"myregistry.azurecr.io": "acr-env"}when the job accesses multiple registries. A globalcredsStoremay invoke the wrong helper for other hosts. - Private or self-hosted registries: Verify the exact OCI registry hostname, repository path, credential format, and upload permission. Do not substitute a web console URL or API endpoint for the registry host.
4. Test network and TLS from the build environment
A registry that works from your laptop may be unreachable from the Kaniko pod. Test DNS and HTTPS from the same namespace or runner network. A temporary diagnostic container can run:
Free tools Windows power users keep installed
One-click scans. No signup required.
nslookup registry.example.com
wget -S -O- https://registry.example.com/v2/A 401 Unauthorized response from /v2/ can be a healthy result: it shows the endpoint is reachable and requires authentication. DNS failure points to name resolution; a timeout suggests egress, firewall, proxy, or registry availability; connection refusal may indicate a wrong endpoint or port. Check network policies, proxy environment variables, firewall rules, and whether the registry is reachable from the build pod—not just from an operator workstation.
For x509: certificate signed by unknown authority, install or configure trust for the correct private CA or complete certificate chain, and verify that the registry hostname matches the certificate. Kaniko provides a registry-certificate option:
/kaniko/executor
--registry-certificate "registry.example.com=/path/to/ca.crt"
--context "$CI_PROJECT_DIR"
--dockerfile "$CI_PROJECT_DIR/Dockerfile"
--destination "registry.example.com/team/app:${IMAGE_TAG}"Kaniko also exposes --skip-tls-verify, --skip-tls-verify-pull, and --skip-tls-verify-registry. These are testing-oriented escape hatches, not production fixes: disabling verification can expose credentials and image contents to interception. The Kaniko documentation lists the options, and GitLab’s documentation describes private-registry certificate troubleshooting.
5. Isolate cache and tag behavior
The final image and Kaniko’s cache may be written to different repositories or governed by different permissions and retention rules. Temporarily disable caching to determine whether the basic image push works:
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Rank #4
/kaniko/executor
--context "$CI_PROJECT_DIR"
--dockerfile "$CI_PROJECT_DIR/Dockerfile"
--destination "registry.example.com/team/app:diagnostic-${CI_JOB_ID}"
--cache=falseUse a unique diagnostic tag so an immutable tag or a competing build does not confuse the result. If this succeeds, inspect the cache repository’s path, existence, permissions, and tag policy. Restore cache only after the basic push succeeds, for example with a separately managed cache repository:
/kaniko/executor
--context "$CI_PROJECT_DIR"
--dockerfile "$CI_PROJECT_DIR/Dockerfile"
--destination "registry.example.com/team/app:${IMAGE_TAG}"
--cache=true
--cache-repo "registry.example.com/team/app-cache"Kaniko documents --no-push-cache; note that --no-push does not necessarily suppress cache-layer pushes unless cache pushing is disabled too. See the project’s flag documentation.
For immutable-tag errors, publish unique build tags or configure release tagging so only one build claims a tag. The option --push-ignore-immutable-tag-errors=true is suitable only when parallel builds deliberately race to publish the same immutable tag and a losing build can safely be treated as successful. It does not make the tag mutable.
6. Use retry and permission-check flags only for the right failure
--push-retry=3may help with transient upload failures, brief timeouts, or temporary registry errors. It will not fix bad credentials, wrong paths, denied permissions, or certificate trust.--skip-push-permission-checkskips Kaniko’s preliminary permission check. It can help if a network policy blocks that check but permits the actual upload; it does not grant permission or repair authentication.--push-ignore-immutable-tag-errors=trueis for a safe, intentional race on immutable tags, not a general push-error fix.
Use debug logs when needed, while ensuring no secret is echoed:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
/kaniko/executor
--verbosity=debug
--context "$CI_PROJECT_DIR"
--dockerfile "$CI_PROJECT_DIR/Dockerfile"
--destination "registry.example.com/team/app:${IMAGE_TAG}"7. Compare with another OCI client
Test the same hostname, repository path, identity, and network path with Docker or another OCI client such as crane or skopeo, if available. Use a unique temporary tag. For example:
Best Value
docker login registry.example.com
docker pull registry.example.com/team/base:tag
docker push registry.example.com/team/test:diagnosticIf that client also fails, focus on credentials, permissions, registry configuration, or connectivity. If it succeeds while Kaniko fails, compare destination parsing, credential-helper behavior, TLS configuration, executor version, and registry compatibility. A successful local push alone is not proof that CI works: the pod may use another identity, token, proxy, DNS view, or certificate trust store.
8. Pin Kaniko and plan for its maintenance status
The official GoogleContainerTools/kaniko repository was archived and made read-only on June 3, 2025. Its changelog lists v1.24.0, released May 21, 2025, as the final upstream release shown; see the changelog. Do not assume a new upstream fix will arrive. This applies to the archived upstream project, not necessarily every downstream fork or vendor-provided image.
If you need to keep a stable pipeline temporarily, pin the executor to a tested version or immutable digest rather than relying on a moving latest tag, and validate that image against the target registry. GitLab’s historical guidance says older Kaniko images can have a compatibility issue with Docker Engine 20.10 or later and recommends at least v1.9.0 in that context; it is not evidence that Kaniko remains actively maintained.
Keep using a pinned Kaniko image as a short-term choice when the pipeline is stable, its registry path and credentials are tested, and your organization accepts the unmaintained-software risk. Plan migration sooner if security rules prohibit archived tooling, the registry changes behavior, a required platform feature is missing, or failures appear intermittent and Kaniko-specific.
Possible replacements include BuildKit/Buildx, Buildah, or a managed CI build service. BuildKit is a natural fit when Dockerfile compatibility and multi-platform builds matter; Kaniko does not provide the same cross-building capability described for BuildKit with QEMU in the archived project’s comparison notes. Buildah may suit teams already using the Red Hat/OCI toolchain or seeking rootless workflows, though storage/runtime configuration can take tuning. Managed services such as GitHub Actions, GitLab CI, Google Cloud Build, AWS CodeBuild, or Azure Pipelines can integrate builder identity and registry access with the surrounding platform, at the cost of platform constraints or vendor dependence. Choose based on your CI environment and security needs, not because a push error alone proves that you should change registry vendors.
Fast diagnostic sequence
- Read the innermost error. Turn on
--verbosity=debugif necessary, and redact secrets from any shared logs. - Normalize the destination. Ensure it has no URL scheme or
/v2/path, and confirm the intended host, repository, and tag. - Check the mounted file. Confirm
/kaniko/.docker/config.jsonexists and is non-empty without printing its contents. - Align hostnames. Compare the destination host,
authsentry, and provider helper configuration. - Test reachability. Query
https://HOST/v2/from the build network; distinguish a reachable401from DNS, timeout, or TLS failure. - Try a unique tag with
--cache=false. This removes cache authorization and tag collisions from the first test. - Verify permissions. Make sure the actual CI workload identity can upload to that exact repository and pull any private base image.
- Re-enable production behavior. Restore cache and release tagging only after the diagnostic push succeeds; if another client works but Kaniko does not, investigate version/helper/compatibility issues and migration options.
For the official flag set, credential examples, and maintenance notice, consult the archived Kaniko project. For a documented MANIFEST_BLOB_UNKNOWN case, see Kaniko issue 3164; treat it as a possible registry interaction rather than proof of a universal cause.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
