can't determine instance name from template locator %#q

Error message

can't determine instance name from template locator %#q

What it means

After successfully reading template bytes, `limactl template validate` requires an instance name to be derivable from the locator. `limatmpl.Read` only sets tmpl.Name when given an explicit name, a template URL, an http/file URL, or a YAML file path; when it cannot (e.g. reading from stdin `-` with no name), the name stays empty and validation aborts because later steps key off the instance name.

Source

Thrown at cmd/limactl/template.go:257

	fill, err := cmd.Flags().GetBool("fill")
	if err != nil {
		return err
	}
	limaDir, err := dirnames.LimaDir()
	if err != nil {
		return err
	}

	for _, arg := range args {
		tmpl, err := limatmpl.Read(ctx, "", arg)
		if err != nil {
			return err
		}
		if len(tmpl.Bytes) == 0 {
			return fmt.Errorf("don't know how to interpret %#q as a template locator", arg)
		}
		if tmpl.Name == "" {
			return fmt.Errorf("can't determine instance name from template locator %#q", arg)
		}
		// Embed default base.yaml only when fill is true.
		if err := tmpl.Embed(cmd.Context(), true, fill); err != nil {
			return err
		}
		// Load() will merge the template with override.yaml and default.yaml via FillDefaults().
		// FillDefaults() needs the potential instance directory to validate host templates using {{.Dir}}.
		filePath := filepath.Join(limaDir, tmpl.Name+".yaml")
		y, err := limayaml.Load(ctx, tmpl.Bytes, filePath)
		if err != nil {
			return err
		}
		// If VMType is not specified, we go with the default platform driver.
		if err := driverutil.ResolveVMType(y); err != nil {
			return err
		}
		if err := limayaml.Validate(y, false); err != nil {
			return fmt.Errorf("failed to validate YAML file %#q: %w", arg, err)

View on GitHub (pinned to dd909d0973)

Solutions

Validate from a named file instead of stdin: `limactl template validate ./my.yaml`
If using stdin is required, add an explicit name via the broader workflow (e.g. `limactl create --name=myinst -`) rather than `template validate -`
Ensure the file path ends in .yaml/.yml so the name can be derived from the basename
Check that the YAML has the fields expected to derive a name if relying on URL-based locators

Example fix

// before
cat my.yaml | limactl template validate -
// after
limactl template validate ./my.yaml

Defensive patterns

Strategy: validation

Validate before calling

if arg == "-" {
	return errors.New("template validate cannot derive an instance name from stdin; use a named .yaml file")
}
if !strings.HasSuffix(arg, ".yaml") && !strings.HasSuffix(arg, ".yml") {
	return fmt.Errorf("cannot derive instance name from %q", arg)
}

Prevention

Prefer validating real files over stdin for `template validate`
Name template files after the intended instance (basename becomes the name)
Use `limactl create --name` when stdin input is required

When it happens

Trigger: Running `limactl template validate -` (reading YAML from stdin) where the YAML does not yield a name, or otherwise supplying a locator for which `InstNameFromYAMLPath`/`InstNameFromURL` cannot derive a name.

Common situations: Piping a config into validate: `cat my.yaml | limactl template validate -`; scripting validate with generated temp input; expecting validate to work like `create --name`.

Related errors

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/ea9c43a15c9b0792. Report an issue: GitHub.