GoogleContainerTools/skaffold · error

unable to expand dockerConfig.path %s

Error message

unable to expand dockerConfig.path %s

What it means

Skaffold failed to expand the `~` shorthand (or other home-relative path) in the cluster's `dockerConfig.path` value. During secret setup (setDefaultClusterDockerConfigSecret), homedir.Expand is called to convert `~/path` into an absolute path; if the home directory cannot be determined (e.g. HOME/USERPROFILE unset), expansion fails and this error is thrown before any cluster interaction.

Source

Thrown at pkg/skaffold/schema/defaults/defaults.go:372

	if cluster.DockerConfig == nil {
		return nil
	}

	random := ""
	if cluster.RandomDockerConfigSecret {
		uid, _ := uuid.NewUUID()
		random = uid.String()
	}

	cluster.DockerConfig.SecretName = valueOrDefault(cluster.DockerConfig.SecretName, kaniko.DefaultDockerConfigSecretName+random)

	if cluster.DockerConfig.Path == "" {
		return nil
	}

	absPath, err := homedir.Expand(cluster.DockerConfig.Path)
	if err != nil {
		return fmt.Errorf("unable to expand dockerConfig.path %s", cluster.DockerConfig.Path)
	}

	cluster.DockerConfig.Path = absPath
	return nil
}

func defaultToKanikoArtifact(artifact *latest.Artifact) {
	if artifact.KanikoArtifact == nil {
		artifact.KanikoArtifact = &latest.KanikoArtifact{}
	}
}

func setKanikoArtifactDefaults(a *latest.KanikoArtifact) {
	a.Image = valueOrDefault(a.Image, kaniko.DefaultImage)
	a.DockerfilePath = valueOrDefault(a.DockerfilePath, constants.DefaultDockerfilePath)
	a.InitImage = valueOrDefault(a.InitImage, constants.DefaultBusyboxImage)
	a.DigestFile = valueOrDefault(a.DigestFile, constants.DefaultKanikoDigestFile)
	if a.Cache != nil {

View on GitHub (pinned to a1189de023)

Solutions

1. Ensure the HOME (or USERPROFILE on Windows) environment variable is set before running skaffold, e.g. `HOME=/root skaffold run`
2. Replace the `~` in dockerConfig.path with the explicit absolute path, e.g. `/home/user/.docker/config.json`
3. Verify the value in skaffold.yaml has no unintended `~` or missing env interpolation; use `${HOME}` style expansion if supported
4. Set dockerConfig.secretName instead of dockerConfig.path if the secret already exists in the cluster

Example fix

# before (skaffold.yaml)
cluster:
  dockerConfig:
    path: ~/.docker/config.json
# after (HOME may be unset in CI)
cluster:
  dockerConfig:
    path: /home/ci/.docker/config.json

path := cluster.DockerConfig.Path
if strings.HasPrefix(path, "~") && os.Getenv("HOME") == "" {
    return fmt.Errorf("dockerConfig.path uses ~ but HOME is not set")
}

func homeExpandable(p string) bool {
    if !strings.HasPrefix(p, "~") { return true }
    _, err := os.UserHomeDir()
    return err == nil
}

When it happens

Trigger: A skaffold.yaml cluster profile sets `cluster.dockerConfig.path` to a path starting with `~` (or a home-relative path), and homedir.Expand cannot resolve it because the HOME environment variable is missing or empty — common when running skaffold inside a container, CI job, or systemd service without HOME set.

Common situations: Running `skaffold` in a Docker/CI container where $HOME is not set; pointing dockerConfig.path at `~/.docker/config.json` in a service account context; typos in dockerConfig.path that rely on an unset env var; Kubernetes exec/remote environments with stripped environment variables.

Related errors

• action %v not found for k8s execution mode
• getting k8s configuration: %w
• unable to get kubernetes config: %w
• unable to get current kubernetes context: %w
• STATUSCHECK_CUSTOM_RESOURCE_FETCH_ERR

AI-assisted analysis of GoogleContainerTools/skaffold@a1189de023 (2026-09-05). Data as JSON: /api/errors/d3cc4c5fafd73e6e. Report an issue: GitHub.