{"record":{"id":"d46cc265bf5fd4e7","repo":"GoogleContainerTools/skaffold","slug":"docker-build-options-secrets-and-ssh-require-bui","errorCode":null,"errorMessage":"docker build options, secrets and ssh, require BuildKit - set `useBuildkit: true` in your config, or run with `DOCKER_BUILDKIT=1`","messagePattern":"docker build options, secrets and ssh, require BuildKit - set `useBuildkit: true` in your config, or run with `DOCKER_BUILDKIT=1`","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/skaffold/docker/image.go","lineNumber":328,"sourceCode":"\tif err == nil {\n\t\tif err := json.Unmarshal(raw, cfg); err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t} else {\n\t\tcfg, err = RetrieveRemoteConfig(image, l.cfg, v1.Platform{})\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t}\n\n\tl.imageCache[image] = cfg\n\n\treturn cfg, nil\n}\n\nfunc (l *localDaemon) CheckCompatible(a *latest.DockerArtifact) error {\n\tif len(a.Secrets) > 0 || a.SSH != \"\" {\n\t\treturn fmt.Errorf(\"docker build options, secrets and ssh, require BuildKit - set `useBuildkit: true` in your config, or run with `DOCKER_BUILDKIT=1`\")\n\t}\n\treturn nil\n}\n\n// Build performs a docker build and returns the imageID.\nfunc (l *localDaemon) Build(ctx context.Context, out io.Writer, workspace string, artifact string, a *latest.DockerArtifact, opts BuildOptions) (string, error) {\n\tlog.Entry(ctx).Debugf(\"Running docker build: context: %s, dockerfile: %s\", workspace, a.DockerfilePath)\n\n\tif err := l.CheckCompatible(a); err != nil {\n\t\treturn \"\", err\n\t}\n\timageInfoEnv, err := EnvTags(opts.Tag)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"couldn't parse image tag: %w\", err)\n\t}\n\tbuildArgs, err := EvalBuildArgsWithEnv(opts.Mode, workspace, a.DockerfilePath, a.BuildArgs, opts.ExtraBuildArgs, imageInfoEnv)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"unable to evaluate build args: %w\", err)","sourceCodeStart":310,"sourceCodeEnd":346,"githubUrl":"https://github.com/GoogleContainerTools/skaffold/blob/a1189de023efc32d4b8e11f395acc678aa555011/pkg/skaffold/docker/image.go#L310-L346","documentation":"Skaffold's local Docker daemon builder refuses to build a Docker artifact that uses build-time secrets or SSH agent forwarding, because those features only work with BuildKit. The daemon path uses the legacy docker build API when BuildKit is disabled, which cannot service `secrets` or `ssh` options, so CheckCompatible fails fast with an actionable message instead of a cryptic remote error.","triggerScenarios":"Calling localDaemon.Build on a *latest.DockerArtifact whose `Secrets` list is non-empty or whose `SSH` field is set, while the skaffold config has useBuildkit disabled/unset and DOCKER_BUILDKIT is not set to 1 in the environment.","commonSituations":"A Dockerfile uses `RUN --mount=type=secret` for tokens or `--mount=type=ssh` for private git clones; the user's skaffold.yaml predates BuildKit defaults or explicitly sets useBuildkit: false; CI environments lack DOCKER_BUILDKIT=1 while a newly added Dockerfile requires BuildKit mounts.","solutions":["Set `useBuildkit: true` on the artifact/builder in your skaffold.yaml","Run skaffold with DOCKER_BUILDKIT=1 exported in the environment","Remove the `secrets`/`ssh` entries from the Docker artifact if they are not needed, replacing them with plain build args where acceptable"],"exampleFix":"// before\nbuild:\n  artifacts:\n    - image: myapp\n      docker:\n        dockerfile: Dockerfile\n        secrets:\n          - id: npm_token,src:/npm_token.txt\n// after\nbuild:\n  artifacts:\n    - image: myapp\n      docker:\n        dockerfile: Dockerfile\n        useBuildkit: true\n        secrets:\n          - id: npm_token,src:./npm_token.txt","handlingStrategy":"validation","validationCode":"func usesBuildkitOnlyFeatures(a *latest.DockerArtifact) bool {\n\treturn len(a.Secrets) > 0 || a.SSH != \"\"\n}\nif usesBuildkitOnlyFeatures(artifact) && os.Getenv(\"DOCKER_BUILDKIT\") != \"1\" {\n\t// enable BuildKit before calling Build\n}","typeGuard":"func needsBuildkit(a *latest.DockerArtifact) bool { return a != nil && (len(a.Secrets) > 0 || a.SSH != \"\") }","tryCatchPattern":"if err := daemon.CheckCompatible(artifact); err != nil {\n\t// surface guidance: enable BuildKit or drop secrets/ssh\n\treturn fmt.Errorf(\"build incompatible: %w\", err)\n}","preventionTips":["Set useBuildkit: true in skaffold.yaml whenever the Dockerfile uses --mount=type=secret or type=ssh","Export DOCKER_BUILDKIT=1 in CI images that run skaffold builds","Call CheckCompatible early in custom pipelines before doing expensive work","Keep Dockerfiles and their skaffold artifact config reviewed together"],"tags":["docker","buildkit","configuration"],"backgroundTag":"buildkit-required-for-feature","analyzedSha":"a1189de023efc32d4b8e11f395acc678aa555011","analyzedAt":"2026-09-05T12:09:27.064Z","contentChangedAt":"2026-09-05T12:09:27.064Z","schemaVersion":2},"datasetVersion":"2026-09-12T17:17:11.597Z"}