lima-vm/lima · error

unknown header: %s

Error message

unknown header: %s

What it means

In snapshotListAction with --quiet, limactl parses the snapshot listing line-by-line and validates that the first line's second field is the literal "TAG" (expected header: ID TAG VM SIZE DATE VM CLOCK ICOUNT). If the header doesn't match, it returns "unknown header: <line>" because the output format can't be trusted for field extraction (tag := fields[1]).

Source

Thrown at cmd/limactl/snapshot.go:204

	if err != nil {
		return err
	}

	quiet, err := cmd.Flags().GetBool("quiet")
	if err != nil {
		return err
	}
	out, err := snapshot.List(ctx, inst)
	if err != nil {
		return err
	}
	if quiet {
		for i, line := range strings.Split(out, "\n") {
			// "ID", "TAG", "VM SIZE", "DATE", "VM CLOCK", "ICOUNT"
			fields := strings.Fields(line)
			if i == 0 && len(fields) > 1 && fields[1] != "TAG" {
				// make sure that output matches the expected
				return fmt.Errorf("unknown header: %s", line)
			}
			if i == 0 || line == "" {
				// skip header and empty line after using split
				continue
			}
			tag := fields[1]
			fmt.Fprintf(cmd.OutOrStdout(), "%s\n", tag)
		}
		return nil
	}
	fmt.Fprint(cmd.OutOrStdout(), out)
	return nil
}

func snapshotBashComplete(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
	return bashCompleteInstanceNames(cmd)
}

View on GitHub (pinned to dd909d0973)

Solutions

1. Run `limactl snapshot list <instance>` without --quiet to inspect the actual raw output
2. If no snapshots exist, create one first or handle the empty case in your script
3. Update lima and the guestagent so host/guest snapshot output versions match
4. Parse the non-quiet output or use `limactl list` fields if you only need instance metadata

Example fix

// before: blindly parsing --quiet output
tags=$(limactl snapshot list --quiet "$inst" | awk '{print $2}')
// after: guard for empty/short output
out=$(limactl snapshot list --quiet "$inst" 2>&1) || { echo "$out"; exit 1; }
[ "$(echo "$out" | wc -l)" -gt 1 ] && tags=$(echo "$out" | tail -n +2 | awk '{print $2}')

out=$(limactl snapshot list "$inst" 2>&1) || { echo "$out"; exit 1; }
echo "$out" | head -n1 | grep -q 'TAG' || { echo 'snapshot listing format unexpected; skipping parse' >&2; exit 0; }

if ! tags=$(limactl snapshot list --quiet "$inst" 2>&1); then
  echo "$tags" >&2; tags=''
fi

When it happens

Trigger: Running `limactl snapshot list --quiet <instance>` when the underlying snapshot tool output changed shape: no snapshots present yielding different output, a non-QEMU driver returning a different listing format, or locale/whitespace changes shifting fields.

Common situations: Scripting --quiet output for empty snapshot lists; driver/backend version mismatch changing column order; parsing assumptions broken after lima or QEMU upgrade; custom LIMA_HOME with stale instance state.

Related errors

• expected tag
• instance %q not found
• disk format %#q not supported, use `qcow2` or `raw` instead
• failed to check if the autostart entry for instance %#q is r
• the YAML is invalid, attempted to save the buffer as %#q but

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