GoogleContainerTools/skaffold · error

unable to expand %q: %w

Error message

unable to expand %q: %w

What it means

ConstructOverrideArgs builds helm CLI arguments, including `--set-file` entries whose values are files. Each value is passed through homedir.Expand (to resolve `~/`); if expansion fails, the error is wrapped as 'unable to expand %q'. This means the path string could not be expanded to an absolute home-directory path.

Source

Thrown at pkg/skaffold/helm/args.go:55

	"github.com/GoogleContainerTools/skaffold/v2/pkg/skaffold/util"
	maps "github.com/GoogleContainerTools/skaffold/v2/pkg/skaffold/util/map"
)

const (
	gcsPrefix        = "gs://"
	valueFileFromGCS = "valuefiles_from_gcs"
)

// ConstructOverrideArgs creates the command line arguments for overrides
func ConstructOverrideArgs(r *latest.HelmRelease, builds []graph.Artifact, args []string, manifestOverrides map[string]string) ([]string, error) {
	for _, k := range maps.SortKeys(r.SetValues) {
		args = append(args, "--set", fmt.Sprintf("%s=%s", k, r.SetValues[k]))
	}

	for _, k := range maps.SortKeys(r.SetFiles) {
		exp, err := homedir.Expand(r.SetFiles[k])
		if err != nil {
			return nil, fmt.Errorf("unable to expand %q: %w", r.SetFiles[k], err)
		}
		exp = SanitizeFilePath(exp, runtime.GOOS == "windows")

		args = append(args, "--set-file", fmt.Sprintf("%s=%s", k, exp))
	}

	envMap := map[string]string{}
	for idx, b := range builds {
		idxSuffix := ""
		// replace commonly used image name chars that are illegal helm template chars "/" & "-" with "_"
		nameSuffix := util.SanitizeHelmTemplateValue(b.ImageName)
		if idx > 0 {
			idxSuffix = strconv.Itoa(idx + 1)
		}

		for k, v := range envVarForImage(b.ImageName, b.Tag) {
			envMap[k+idxSuffix] = v
			envMap[k+"_"+nameSuffix] = v

View on GitHub (pinned to a1189de023)

Solutions

1. Set the HOME environment variable in the environment running Skaffold (common in containers/CI).
2. Replace `~/`-relative paths with absolute paths in the helm `setFiles` configuration.
3. Fix empty or malformed setFiles values in skaffold.yaml.
4. Verify with `echo $HOME` that the running process can resolve the home directory.

Example fix

// before (skaffold.yaml)
setFiles: { config: ~/charts/config.yaml }
// after (absolute path, or ensure HOME is set)
setFiles: { config: /opt/charts/config.yaml }

for k, v := range helmConfig.SetFiles {
	if v == "" {
		return fmt.Errorf("helm setFiles[%s] is empty", k)
	}
	if strings.HasPrefix(v, "~/") && os.Getenv("HOME") == "" {
		return fmt.Errorf("HOME unset; setFiles[%s] uses ~ path", k)
	}
}

When it happens

Trigger: Calling ConstructOverrideArgs (via installArgs/templateArgs, i.e. `skaffold helm install/upgrade/template`) with a helm `setFiles` entry whose value fails homedir.Expand — in practice a value that cannot be resolved against the user's home directory, e.g. an empty or malformed `~`-relative path.

Common situations: skaffold.yaml helm releases config with `setFiles` entries using `~/...` while HOME is unset (containers, CI); an empty string or typo in the setFiles value.

Related errors

• duplicate release name %s
• release %s depends on non-existent release %s
• unable to create dependency graph: %w
• unable to get releases by level: %w
• cannot parse the release namespace template: %w

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