What causes "unknown column: %s (valid: %s)" in muesli/duf?

Use one of the valid IDs listed in the error message's (valid: ...) suffix.

unknown column: %s (valid: %s)

Error message

unknown column: %s (valid: %s)

What it means

stringToColumn converts a column name string to its index in the columns table by comparing against each column's ID. If no column matches, it returns "unknown column: %s (valid: %s)" including the full list of valid IDs. Used when parsing user-specified output columns.

Source

Thrown at table.go:550

			return
		}
	} else {
		size = num
	}
	return
}

// stringToColumn converts a column name to its index.
func stringToColumn(s string) (int, error) {
	s = strings.ToLower(s)

	for i, v := range columns {
		if v.ID == s {
			return i + 1, nil
		}
	}

	return 0, fmt.Errorf("unknown column: %s (valid: %s)", s, strings.Join(columnIDs(), ", "))
}

// stringToSortIndex converts a column name to its sort index.
func stringToSortIndex(s string) (int, error) {
	s = strings.ToLower(s)

	for _, v := range columns {
		if v.ID == s {
			return v.SortIndex, nil
		}
	}

	return 0, fmt.Errorf("unknown column: %s (valid: %s)", s, strings.Join(columnIDs(), ", "))
}

// columnsIDs returns a slice of all column IDs.
func columnIDs() []string {
	s := make([]string, len(columns))

View on GitHub (pinned to 4636deb4a7)

Solutions

Use one of the valid IDs listed in the error message's (valid: ...) suffix.
Check spelling and case against the error's valid list.
Update scripts to column IDs if the tool version changed the set of columns.

Example fix

// before
--columns device,filesystem
// after
--columns device,fs

Defensive patterns

Strategy: validation

Validate before calling

valid := strings.Join(columnIDs(), ",")
for _, c := range strings.Split(columnsFlag, ",") {
	if !strings.Contains(","+valid+",", ","+c+",") { /* unknown column */ }
}

Try / catch

idx, err := stringToColumn(name)
if err != nil {
	return fmt.Errorf("%w; use one of: %s", err, strings.Join(columnIDs(), ", "))
}

Prevention

Use only column IDs from the (valid: ...) list in the error.
Watch for abbreviations (fs, not filesystem).
Regenerate hardcoded column lists when upgrading the tool.

When it happens

Trigger: parseColumns receives a --columns value (case-sensitive, lowercased by the caller) that is not a known column ID, e.g. --columns device,filesystem when only "device", "used", etc. exist.

Common situations: Typos in column names, assuming full names like "filesystem" where the ID is abbreviated (e.g. "fs"), or using column names from different disk-usage tools (df -h style headers).

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of muesli/duf@4636deb4a7 (2026-09-06). Data as JSON: /api/errors/4546f06077a8669e. Report an issue: GitHub.