lima-vm/lima · error

template does not define param %#q

Error message

template does not define param %#q

What it means

BuildParamExpressions validates each NAME=VALUE parameter against the set of parameters the target template actually defines (allowedParams). This error is returned when the NAME is not a defined param in the template, so the override would have no effect or produce an invalid yq expression.

Solutions

1. Inspect the template and use exactly its declared param names (e.g. --param cpus=4)
2. Fix typos in the parameter NAME
3. Use the appropriate generic flags (e.g. --cpus) instead of --param when the template has no such param
4. Update to a template version that still defines the param

Example fix

// before
limactl create template://_default --param cpuCount=4
// after
limactl create template://_default --param cpus=4

for _, p := range params {
	key, _, _ := strings.Cut(p, "=")
	if _, ok := allowedParams[key]; !ok {
		return fmt.Errorf("template defines no param %q; allowed: %v", key, keysOf(allowedParams))
	}
}

func paramAllowed(key string, allowed map[string]string) bool {
	_, ok := allowed[key]
	return ok
}

exprs, err := editflags.BuildParamExpressions(params, allowedParams)
if err != nil {
	return fmt.Errorf("--param rejected: %w (check the template's defined params)", err)
}

When it happens

Trigger: Calling BuildParamExpressions with a key absent from allowedParams, e.g. --param cpuCount=4 against a template whose params only define 'cpus'; also happens when passing params to a template with no params at all.

Common situations: Typos in parameter names (cpus vs cpuCount vs cpu); using params from one template with another template; version drift where a template renamed or removed a param; forgetting the template:// prefix format differences.

Related errors

• invalid parameter %#q, expected NAME=VALUE
• another hostagent may already be running with pid
• can't determine instance name from template locator %#q
• don't know how to interpret %#q as a template locator
• failed to determine if another hostagent is running

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

Appendix: source

Thrown at cmd/limactl/editflags/editflags.go:193

		hostPort, guestPort, isStatic, err := ParsePortForward(spec)
		if err != nil {
			return "", err
		}
		ports[i] = fmt.Sprintf(`{"guestPort": %q, "hostPort": %q, "static": %v}`, guestPort, hostPort, isStatic)
	}
	expr := fmt.Sprintf(".portForwards += [%s]", strings.Join(ports, ","))
	return expr, nil
}

func BuildParamExpressions(params []string, allowedParams map[string]string) ([]string, error) {
	exprs := make([]string, len(params))
	for i, param := range params {
		key, value, ok := strings.Cut(param, "=")
		if !ok {
			return nil, fmt.Errorf("invalid parameter %#q, expected NAME=VALUE", param)
		}
		if _, ok := allowedParams[key]; !ok {
			return nil, fmt.Errorf("template does not define param %#q", key)
		}
		exprs[i] = fmt.Sprintf(".param[%q] = %q", key, value)
	}
	return exprs, nil
}

func buildMountListExpression(ss []string) (string, error) {
	mounts := make([]string, len(ss))
	for i, s := range ss {
		writable := strings.HasSuffix(s, ":w")
		loc, err := localpathutil.Expand(strings.TrimSuffix(s, ":w"))
		if err != nil {
			return "", err
		}
		mounts[i] = fmt.Sprintf(`{"location": %q, "mountPoint": %q, "writable": %v}`, loc, loc, writable)
	}
	expr := fmt.Sprintf("[%s]", strings.Join(mounts, ","))
	return expr, nil

View on GitHub (pinned to dd909d0973)