Common issues

Common failures when running `seal image fix`, and how to resolve them.

denied: requested access to the resource is denied

What's happening: Docker on the host running seal image fix cannot authenticate against the source or destination registry. The error comes from docker pull or docker push, not from Seal.

Resolution: Re-run the registry-login step for the failing registry. See Authenticating with your container registry. A quick smoke test is to docker pull <source-image> and docker push <destination-tag> directly, outside the Seal CLI, and confirm both succeed.

For cloud-provider registries (ECR, GCP Artifact Registry, ACR), credentials expire on a short cadence. Make sure the CI runner refreshes them at the start of every job.

The CLI cannot detect the distribution

What's happening: The image's root filesystem does not expose enough information for the CLI to identify which OS-package family is in use (typically because /etc/os-release is missing or empty).

Resolution: Re-run with increased verbosity (-vvvv) to see exactly which files the CLI tried to read. If the image is a deliberately stripped-down minimal image and is expected to have those files, restore them in a prior layer. If the image is distroless, the CLI should still work — distroless images preserve enough of the underlying distribution's metadata for the CLI to handle them; if it does not, contact your Seal account team with the image reference.

failed to compute cache key or --mount=type=secret errors

What's happening: BuildKit is not enabled on the host's Docker daemon, or the Docker version is too old to support --mount=type=secret.

Resolution: Confirm BuildKit is enabled: DOCKER_BUILDKIT=1 in the environment, or "features": {"buildkit": true} in /etc/docker/daemon.json. Recent Docker versions (20.10+) enable BuildKit by default; older versions may not. If you cannot upgrade Docker, set DOCKER_BUILDKIT=1 in the shell running seal image fix.

failed to seal with no further detail in stderr

What's happening: The seal step inside the generated Dockerfile failed, and the build output Docker prints does not include the underlying CLI error.

Resolution: Re-run with increased verbosity: -vvvv on the persistent flag. The CLI's debug output appears in the docker build log; look for the seal fix --os lines and their associated error.

A common underlying cause: the SEAL_TOKEN passed via --build-arg instead of --secret. seal image fix expects the token in the host environment; the CLI then plumbs it into the build via --mount=type=secret. Setting SEAL_TOKEN as a --build-arg on docker build directly (instead of in the host's env) does not work and is detected as a permission failure inside the build.

The sealed image is much larger than the source

What's happening: Layers added by the seal step (the CLI binary, the downloaded sealed package files) increased the image size.

Resolution: The CLI's --remove-cli flag (passed through automatically by seal image fix) removes the CLI binary from the resulting image. The remaining size increase is from the sealed packages themselves, which replace the original packages and are roughly the same size — typically within 1-3% of the original.

If the difference is much larger than that, the package manager has retained transitional files. For apt, run apt-get clean in a layer after the seal step (you cannot edit the generated Dockerfile, but you can repoint seal image fix at an image that already has those steps in its own Dockerfile). For dnf, the equivalent is dnf clean all.

The seal step succeeds but the image still flags as vulnerable in the external scanner

What's happening: The external scanner compares the package-database names against a public vulnerability feed and reports against the original names that are still in the database.

Resolution: Enable package renaming by setting SEAL_USE_SEALED_NAMES=1 in the environment before seal image fix runs. The renamed packages do not appear in the public feed.

If the scanner accepts Seal's vulnerability feed directly (Trivy and Wiz can, with configuration), use the feed-integration path instead — it is preferred over renaming-in-image where it works. The feed-integration setup is documented under External scanners.

The application fails to start after seal

What's happening: A sealed package is incompatible with the application's expectations. This is rare; sealed packages are designed to be drop-in replacements for their upstream counterparts.

Resolution: First, confirm the failure is sealed-package-specific by running the original image against the same test: if the unsealed image also fails, the seal step is not the cause. If only the sealed image fails, identify the sealed package(s) the application uses and either:

• Pin the unsealed version of the offending package by creating a Sealing Rule for that specific package and pointing seal image fix at the corresponding fix mode (--mode remote to use the rule), or

• Contact your Seal account team with the symptoms; they can confirm the sealed iteration's status and, if needed, ship a corrected sealed version.

A regression specific to a sealed iteration is uncommon. The more frequent cause is that the application depended on a behavior the upstream version itself had a bug in, and the sealed version corrected it.

seal image fix runs forever / never returns

What's happening: The underlying docker build is hanging. This usually means the build is stuck on a network operation — downloading the sealed packages from the matching Seal OS artifact server.

Resolution: Confirm the build host has outbound HTTPS connectivity to the relevant Seal OS artifact server (apk.sealsecurity.io, deb.sealsecurity.io, or rpm.sealsecurity.io). The seal step inside the generated Dockerfile runs seal fix --os, which needs to reach Seal's hosted servers. A misconfigured corporate proxy or a missing CA bundle is the usual culprit.

Related

• The seal image fix command and flags: the full reference.

• Authenticating with your container registry: the credential-related issues.

• Renaming packages inside containers: the external-scanner-flagging case.