# Error: cache from ref docker.io/library/python:3.11-slim: cache policy violation: layer 2a3b4c5d6e7f is not allowed by cache policy 'cache-to: type=local'

- **ID:** `policy/docker-layer-cache-policy-violation`
- **Domain:** policy
- **Category:** config_error
- **Verification:** ai_generated
- **Fix Rate:** 78%

## Root Cause

Docker BuildKit's cache policy configuration (cache-to/cache-from) has a mismatch between the specified cache export type and the layer's origin, often when trying to export cache from a registry image to a local directory.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Docker 24.0.x | active | — | — |
| Docker 25.0.x | active | — | — |
| Docker 26.0.x | active | — | — |

## Workarounds

1. **Use a compatible cache export type. If using 'cache-to: type=local', ensure the cache source is also from a local build, not a registry image. Alternatively, use 'type=registry' for registry-based caching.
Example:
  docker build --cache-from type=registry,ref=myregistry.com/myimage:cache \
               --cache-to type=registry,ref=myregistry.com/myimage:cache,mode=max .** (85% success)
   ```
   Use a compatible cache export type. If using 'cache-to: type=local', ensure the cache source is also from a local build, not a registry image. Alternatively, use 'type=registry' for registry-based caching.
Example:
  docker build --cache-from type=registry,ref=myregistry.com/myimage:cache \
               --cache-to type=registry,ref=myregistry.com/myimage:cache,mode=max .
   ```
2. **Disable cache policy enforcement by using '--cache-from' without '--cache-to' or use 'mode=min' for cache-to to export only the final layer.
Example:
  docker build --cache-from type=local,src=path/to/cache \
               --cache-to type=local,dest=path/to/cache,mode=min .** (75% success)
   ```
   Disable cache policy enforcement by using '--cache-from' without '--cache-to' or use 'mode=min' for cache-to to export only the final layer.
Example:
  docker build --cache-from type=local,src=path/to/cache \
               --cache-to type=local,dest=path/to/cache,mode=min .
   ```
3. **Rebuild the base image locally and use it as a local cache source to avoid policy violations with registry-sourced layers.
Example:
  # Build base image locally
  docker build -t mybase:latest -f Dockerfile.base .
  # Use it as cache source
  docker build --cache-from type=local,src=path/to/cache --cache-to type=local,dest=path/to/cache .** (70% success)
   ```
   Rebuild the base image locally and use it as a local cache source to avoid policy violations with registry-sourced layers.
Example:
  # Build base image locally
  docker build -t mybase:latest -f Dockerfile.base .
  # Use it as cache source
  docker build --cache-from type=local,src=path/to/cache --cache-to type=local,dest=path/to/cache .
   ```

## Dead Ends

- **Clearing all Docker cache and rebuilding** — Clearing all Docker cache and rebuilding from scratch loses all caching benefits and may not resolve the policy mismatch if the same configuration is used. (40% fail)
- **Changing the base image** — Changing the base image to a different version might bypass the specific layer but the underlying policy issue remains for other layers. (65% fail)
- **Running docker system prune -a** — Running 'docker system prune -a' removes all images and containers but does not fix the cache policy configuration in the Dockerfile or build command. (75% fail)