lima-vm/lima · error

option --yq only works with --format json or yaml

Error message

option --yq only works with --format json or yaml

What it means

--yq post-processes output as YAML/JSON via the yq expression engine, so it only makes sense when the underlying format is json or yaml. If an explicit --format (like table or a custom one) was given alongside --yq, listAction rejects it.

Source

Thrown at cmd/limactl/list.go:169

	filter, err := cmd.Flags().GetStringArray("filter")
	if err != nil {
		return err
	}

	if jsonFormat {
		format = "json"
	}

	// conflicts
	if jsonFormat && cmd.Flags().Changed("format") {
		return errors.New("option --json conflicts with option --format")
	}
	if listFields && cmd.Flags().Changed("format") {
		return errors.New("option --list-fields conflicts with option --format")
	}
	if len(yq) != 0 {
		if cmd.Flags().Changed("format") && format != "json" && format != "yaml" {
			return errors.New("option --yq only works with --format json or yaml")
		}
		if listFields {
			return errors.New("option --list-fields conflicts with option --yq")
		}
	}
	if len(filter) != 0 {
		if listFields {
			return errors.New("option --list-fields conflicts with option --filter")
		}
	}

	if quiet && format != "table" {
		return errors.New("option --quiet can only be used with '--format table'")
	}

	if listFields {
		names := fieldNames()
		slices.Sort(names)

View on GitHub (pinned to dd909d0973)

Solutions

  1. Use `--format json --yq '...'` or `--format yaml --yq '...'`
  2. Drop --format entirely (default format is compatible with --yq)
  3. Remove --yq if you truly want human-readable table output

Example fix

// before
limactl list --yq '.[0].status' --format table
// after
limactl list --yq '.[0].status' --format json
Defensive patterns

Strategy: validation

Validate before calling

if slices.Contains(os.Args, "--yq") && (slices.Contains(os.Args, "--format") && !hasJSONOrYAMLFormat(os.Args)) {
    // drop --format or switch to json/yaml before invoking
}

func hasJSONOrYAMLFormat(args []string) bool {
    for i, a := range args {
        if a == "--format" && i+1 < len(args) && (args[i+1] == "json" || args[i+1] == "yaml") { return true }
    }
    return false
}

Try / catch

if err := runList(); err != nil {
    if strings.Contains(err.Error(), "--yq only works with") { /* retry with --format json */ }
    return err
}

Prevention

When it happens

Trigger: Running e.g. `limactl list --yq '.[0].status' --format table` — yq is non-empty, --format was explicitly changed, and the value is neither json nor yaml. (Note: --yq with the default format works because the default is json.)

Common situations: Copy-pasting a --yq example while also adding --format table for readability; scripts where --format was added for humans but --yq kept for machines.

Related errors

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