{
  "id": "policy/docker-layer-cache-policy-violation",
  "signature": "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'",
  "signature_zh": "错误：从引用 docker.io/library/python:3.11-slim 的缓存：缓存策略违规：层 2a3b4c5d6e7f 不被缓存策略 'cache-to: type=local' 允许",
  "regex": "cache from ref .*: cache policy violation: layer [a-f0-9]+ is not allowed by cache policy 'cache-to: type=local'",
  "domain": "policy",
  "category": "config_error",
  "subcategory": null,
  "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.",
  "root_cause_type": "generic",
  "root_cause_zh": "Docker BuildKit 的缓存策略配置（cache-to/cache-from）在指定的缓存导出类型和层的来源之间存在不匹配，通常发生在尝试将缓存从注册表镜像导出到本地目录时。",
  "versions": [
    {
      "version": "Docker 24.0.x",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Docker 25.0.x",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Docker 26.0.x",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Clearing all Docker cache and rebuilding",
      "why_fails": "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.",
      "fail_rate": 0.4,
      "condition": "",
      "sources": []
    },
    {
      "action": "Changing the base image",
      "why_fails": "Changing the base image to a different version might bypass the specific layer but the underlying policy issue remains for other layers.",
      "fail_rate": 0.65,
      "condition": "",
      "sources": []
    },
    {
      "action": "Running docker system prune -a",
      "why_fails": "Running 'docker system prune -a' removes all images and containers but does not fix the cache policy configuration in the Dockerfile or build command.",
      "fail_rate": 0.75,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "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.\nExample:\n  docker build --cache-from type=registry,ref=myregistry.com/myimage:cache \\\n               --cache-to type=registry,ref=myregistry.com/myimage:cache,mode=max .",
      "success_rate": 0.85,
      "how": "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.\nExample:\n  docker build --cache-from type=registry,ref=myregistry.com/myimage:cache \\\n               --cache-to type=registry,ref=myregistry.com/myimage:cache,mode=max .",
      "condition": "",
      "sources": []
    },
    {
      "action": "Disable cache policy enforcement by using '--cache-from' without '--cache-to' or use 'mode=min' for cache-to to export only the final layer.\nExample:\n  docker build --cache-from type=local,src=path/to/cache \\\n               --cache-to type=local,dest=path/to/cache,mode=min .",
      "success_rate": 0.75,
      "how": "Disable cache policy enforcement by using '--cache-from' without '--cache-to' or use 'mode=min' for cache-to to export only the final layer.\nExample:\n  docker build --cache-from type=local,src=path/to/cache \\\n               --cache-to type=local,dest=path/to/cache,mode=min .",
      "condition": "",
      "sources": []
    },
    {
      "action": "Rebuild the base image locally and use it as a local cache source to avoid policy violations with registry-sourced layers.\nExample:\n  # Build base image locally\n  docker build -t mybase:latest -f Dockerfile.base .\n  # Use it as cache source\n  docker build --cache-from type=local,src=path/to/cache --cache-to type=local,dest=path/to/cache .",
      "success_rate": 0.7,
      "how": "Rebuild the base image locally and use it as a local cache source to avoid policy violations with registry-sourced layers.\nExample:\n  # Build base image locally\n  docker build -t mybase:latest -f Dockerfile.base .\n  # Use it as cache source\n  docker build --cache-from type=local,src=path/to/cache --cache-to type=local,dest=path/to/cache .",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "使用兼容的缓存导出类型。如果使用 'cache-to: type=local'，确保缓存源也来自本地构建，而不是注册表镜像。或者，对于基于注册表的缓存，使用 'type=registry'。\n示例：\n  docker build --cache-from type=registry,ref=myregistry.com/myimage:cache \\\n               --cache-to type=registry,ref=myregistry.com/myimage:cache,mode=max .",
    "通过仅使用 '--cache-from' 而不使用 '--cache-to' 来禁用缓存策略强制执行，或者为 cache-to 使用 'mode=min' 以仅导出最终层。\n示例：\n  docker build --cache-from type=local,src=path/to/cache \\\n               --cache-to type=local,dest=path/to/cache,mode=min .",
    "在本地重建基础镜像并将其用作本地缓存源，以避免与注册表来源的层发生策略违规。\n示例：\n  # 本地构建基础镜像\n  docker build -t mybase:latest -f Dockerfile.base .\n  # 将其用作缓存源\n  docker build --cache-from type=local,src=path/to/cache --cache-to type=local,dest=path/to/cache ."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.docker.com/build/cache/",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.83,
  "fix_success_rate": 0.78,
  "resolvable": "true",
  "first_seen": "2024-03-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}