don't know how to interpret %#q as a template locator

Error message

don't know how to interpret %#q as a template locator

What it means

`limactl template copy` calls `limatmpl.Read` on the source locator; Read returns a Template with empty Bytes when the locator matched an image-URL pattern (img/iso/etc.) rather than a YAML template. The action then rejects it because there is no template content to copy. It is a user-input classification error, not an internal failure.

Source

Thrown at cmd/limactl/template.go:138

	verbatim, err := cmd.Flags().GetBool("verbatim")
	if err != nil {
		return err
	}
	if fill {
		embedAll = true
	}
	if embedAll {
		embed = true
	}
	if embed && verbatim {
		return errors.New("--verbatim cannot be used with any of --embed, --embed-all, or --fill")
	}
	tmpl, err := limatmpl.Read(ctx, "", source)
	if err != nil {
		return err
	}
	if len(tmpl.Bytes) == 0 {
		return fmt.Errorf("don't know how to interpret %#q as a template locator", source)
	}
	if !verbatim {
		if embed {
			// Embed default base.yaml only when fill is true.
			if err := tmpl.Embed(ctx, embedAll, fill); err != nil {
				return err
			}
		} else {
			if err := tmpl.UseAbsLocators(ctx); err != nil {
				return err
			}
		}
	}
	if fill {
		if err := fillDefaults(ctx, tmpl); err != nil {
			return err
		}
	}

View on GitHub (pinned to dd909d0973)

Solutions

Pass a YAML template locator (a template name like `default`, a local .yaml path, an http(s) URL to YAML, or `-` for stdin) as the source
If you meant to copy a VM image, use the image in a template's images list instead of `template copy`
Check the extension/URL of the source; rename or point to the .yaml file
Run `limactl template ls` to list valid template names

Example fix

// before
limactl template copy https://example.com/ubuntu-24.04.img my.yaml
// after
limactl template copy template://default my-copy.yaml  # or a path to a .yaml file

Defensive patterns

Strategy: validation

Validate before calling

func isValidTemplateLocator(src string) bool {
	if src == "-" || strings.HasSuffix(src, ".yaml") || strings.HasSuffix(src, ".yml") {
		return true
	}
	imageRe := regexp.MustCompile(`\.(img|qcow2|raw|iso|ipsw)(\.(gz|xz|bz2|zstd))?$`)
	return !imageRe.MatchString(src)
}
if !isValidTemplateLocator(source) {
	return fmt.Errorf("%q is a VM image, not a YAML template", source)
}

Prevention

Always pass .yaml/.yml files or template:// names to `template copy`
Never point template commands at disk images (.img/.iso/...); images belong in a template's images list
Use `limactl template ls` to discover valid built-in template names
Check file size > 0 before passing a local file as a template

When it happens

Trigger: Running `limactl template copy <src> <dst>` where src resolves to a VM image locator (e.g. a URL or path ending in .img, .qcow2, .raw, .iso, .ipsw, optionally compressed) instead of a YAML template, or an empty/unreadable source that produced zero bytes.

Common situations: Passing a disk image URL copied from a release page instead of a template YAML; expecting `template copy` to duplicate a base image; typos like copying an .iso file; pointing at an empty file.

Related errors

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