What causes "error while interpolating %s: %w" in docker/cli?

Set the missing variable in the environment or a .env file.

error while interpolating

Error message

error while interpolating %s: %w

What it means

Returned by newPathError as the catch-all for interpolation errors that are not *template.InvalidTemplateError (interpolation.go:110-112). The most common inner cause is a required variable referenced with ${VAR} (no default) that is not present in the lookup map, which the template engine reports as a 'required variable' error.

Solutions

Set the missing variable in the environment or a .env file.
Provide a default with ${VAR:-default} if the variable is optional.
Use ${VAR?error message} intentionally only where you want a clear failure.

Example fix

# before
services:
  app:
    image: app:${TAG}
# after (give a default)
services:
  app:
    image: app:${TAG:-latest}

Defensive patterns

Strategy: try-catch

Validate before calling

// Provide defaults for optional vars to avoid 'required variable' errors.
// In compose: image: app:${TAG:-latest}
// Programmatically, ensure all required vars are present:
func ensureEnv(vars ...string) error {
    for _, v := range vars {
        if _, ok := os.LookupEnv(v); !ok {
            return fmt.Errorf("required env var %s is not set", v)
        }
    }
    return nil
}

Try / catch

loaded, err := loader.Load(details)
if err != nil {
    if strings.Contains(err.Error(), "interpolating") {
        // likely a missing required variable; prompt for / set the env var and retry
    }
    return err
}

Prevention

Provide defaults (${VAR:-default}) for optional variables.
Load a .env file or export required vars before running compose.
Use ${VAR?reason} only where you want an explicit, named failure.

When it happens

Trigger: A compose value references ${VAR} (or ${VAR?...}) and VAR is not set in the environment/lookup, and the template engine treats it as required. Also any non-InvalidTemplateError returned by the Substitute function lands here.

Common situations: Forgetting to export an env var the compose file expects; running on a host/CI without the .env file loaded; referencing a secret/variable that is intentionally required to fail fast.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/6cf04fcb93b6cf39. Report an issue: GitHub.

Appendix: source

Thrown at cli/compose/interpolation/interpolation.go:111

			out[i] = interpolatedElem
		}
		return out, nil

	default:
		return value, nil
	}
}

func newPathError(path Path, err error) error {
	switch err := err.(type) {
	case nil:
		return nil
	case *template.InvalidTemplateError:
		return fmt.Errorf(
			"invalid interpolation format for %s: %#v; you may need to escape any $ with another $",
			path, err.Template)
	default:
		return fmt.Errorf("error while interpolating %s: %w", path, err)
	}
}

const pathSeparator = "."

// PathMatchAll is a token used as part of a Path to match any key at that level
// in the nested structure
const PathMatchAll = "*"

// PathMatchList is a token used as part of a Path to match items in a list
const PathMatchList = "[]"

// Path is a dotted path of keys to a value in a nested mapping structure. A *
// section in a path will match any key in the mapping structure.
type Path string

// NewPath returns a new Path
func NewPath(items ...string) Path {

View on GitHub (pinned to 4f84911bfe)