lima-vm/lima · error

failed to validate YAML file %#q: %w

Error message

failed to validate YAML file %#q: %w

What it means

`limactl template validate` loads the YAML, fills defaults, resolves the VM type, and then runs `limayaml.Validate`. This wrapper error reports that the (default-filled) YAML failed Lima's schema/semantic validation, with the underlying validator error attached via %w.

Source

Thrown at cmd/limactl/template.go:275

			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)
		}
		logrus.Infof("%#q: OK", arg)
		if fill {
			b, err := limayaml.Marshal(y, len(args) > 1)
			if err != nil {
				return fmt.Errorf("failed to marshal template %#q again after filling defaults: %w", arg, err)
			}
			fmt.Fprint(cmd.OutOrStdout(), string(b))
		}
	}

	return nil
}

func newTemplateURLCommand() *cobra.Command {
	templateURLCommand := &cobra.Command{
		Use:   "url CUSTOM_URL",
		Short: "Transform custom template URLs to regular file or https URLs",

View on GitHub (pinned to dd909d0973)

Solutions

1. Read the wrapped `%w` cause — it names the offending field and expected values
2. Fix the reported field in the YAML (correct field names per current Lima schema)
3. Run `limactl template validate --fill <file>` to see the fully defaulted YAML and confirm resulting values
4. Test against a known-good template: copy template://default and edit incrementally
5. Upgrade/downgrade checks: fields from an older Lima version may no longer validate

Example fix

// before
cpus: 4        # unknown field
vm_type: qemu  # wrong name
// after
cpus: 4
vmType: qemu

// Sanity-check before invoking validate
b, err := os.ReadFile(arg)
if err != nil { return err }
var doc map[string]any
if err := yaml.Unmarshal(b, &doc); err != nil {
	return fmt.Errorf("%s is not valid YAML: %w", arg, err)
}

if err := limayaml.Validate(y, false); err != nil {
	var fieldErr *ValidationError
	if errors.As(err, &fieldErr) {
		log.Printf("fix field %s: %v", fieldErr.Field, fieldErr)
	}
	return fmt.Errorf("failed to validate YAML file %q: %w", arg, err)
}

When it happens

Trigger: Running `limactl template validate <file>` (or `--fill`) on a YAML whose content violates limayaml constraints: unknown fields, invalid arch/os/vmType values, bad image URLs, invalid disk/memory sizes, conflicting settings, etc.

Common situations: Hand-edited templates with typos (e.g. `cpu: 4` instead of `cpus: 4`); templates copied from older Lima versions using removed/renamed fields; invalid arch like `arm` on an amd64 host; malformed mounts or port mappings.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• the YAML is invalid, attempted to save the buffer as %#q but
• the YAML is invalid, saved the buffer as %#q: %w
• failed to validate the instance YAML after filling defaults:
• disk format %#q not supported, use `qcow2` or `raw` instead
• invalid port forward format %#q, expected HOST:GUEST or HOST

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