> ## Documentation Index
> Fetch the complete documentation index at: https://tally.wharflab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# buildkit/InvalidBaseImagePlatform

> Validates that the platform of an external base image matches the expected target platform.

Validates that the platform of an external base image matches the expected target platform.

| Property | Value                                                                            |
| -------- | -------------------------------------------------------------------------------- |
| Severity | Off                                                                              |
| Category | Correctness                                                                      |
| Default  | Disabled (superseded by [`tally/platform-mismatch`](../tally/platform-mismatch)) |

## Tally behavior deviation

Tally disables this rule by default because its host-dependent design is
fundamentally broken for a static linter:

* **Non-deterministic results across machines.** The rule compares resolved
  image platforms against the host's default platform (via `runtime.GOARCH`).
  The same Dockerfile produces different violations on `linux/amd64` CI vs
  `macOS/arm64` developer laptops.
* **False positives on Windows containers.** The expected OS is hardcoded to
  `"linux"`, so any Windows base image (e.g.,
  `mcr.microsoft.com/windows/servercore`) is always flagged as a mismatch.
* **Fires without explicit intent.** When no `--platform` flag is set on
  `FROM`, the rule still compares against the host — even though the builder
  will pick the correct platform at build time.

Use [`tally/platform-mismatch`](../tally/platform-mismatch) instead. That
rule only fires when `--platform` is explicitly set on `FROM` and the registry
does not provide the requested platform, producing deterministic results
regardless of host.

You can re-enable this rule via configuration if you prefer the BuildKit
behavior:

```yaml theme={null}
rules:
  buildkit/InvalidBaseImagePlatform:
    severity: error
```

## Description

When using `--platform` or `$TARGETPLATFORM`, this rule checks that the base
image actually supports the requested platform by resolving image metadata from
the registry.

This is an async rule that runs with `--slow-checks`, as it requires resolving
image metadata from the registry.

## Examples

Bad (image not available for requested platform):

```dockerfile theme={null}
FROM --platform=linux/s390x ubuntu:22.04
# Error if ubuntu:22.04 is not available for linux/s390x
```

Good:

```dockerfile theme={null}
FROM --platform=linux/amd64 ubuntu:22.04
```

The error message includes available platforms:

```text theme={null}
Base image ubuntu:22.04 was pulled with platform "linux/arm64", expected "linux/s390x" for current build
```

## See also

* [`tally/platform-mismatch`](../tally/platform-mismatch) — deterministic replacement that only validates explicit `--platform` flags