What causes "separator must be single character" in charmbracelet/gum?

Pass exactly one character: -s ';' or -s ','.

separator must be single character

Error message

separator must be single character

What it means

Gum table uses the --separator flag as the CSV field delimiter and validates it is exactly one rune. Passing an empty string or a multi-character string fails this check before parsing.

Source

Thrown at table/command.go:45

		input, err = os.Open(o.File)
		if err != nil {
			return fmt.Errorf("could not render file: %w", err)
		}
	} else {
		if stdin.IsEmpty() {
			return fmt.Errorf("no data provided")
		}
		input = os.Stdin
	}
	defer input.Close() //nolint: errcheck

	transformer := unicode.BOMOverride(encoding.Nop.NewDecoder())
	reader := csv.NewReader(transform.NewReader(input, transformer))
	reader.LazyQuotes = o.LazyQuotes
	reader.FieldsPerRecord = o.FieldsPerRecord
	separatorRunes := []rune(o.Separator)
	if len(separatorRunes) != 1 {
		return fmt.Errorf("separator must be single character")
	}
	reader.Comma = separatorRunes[0]

	writer := csv.NewWriter(os.Stdout)
	writer.Comma = separatorRunes[0]

	var columnNames []string
	var err error
	// If no columns are provided we'll use the first row of the CSV as the
	// column names.
	if len(o.Columns) <= 0 {
		columnNames, err = reader.Read()
		if err != nil {
			return fmt.Errorf("unable to parse columns")
		}
	} else {
		columnNames = o.Columns
	}

View on GitHub (pinned to 4d089f9550)

Solutions

Pass exactly one character: -s ';' or -s ','.
For tabs, use a real tab: -s $'\t' (bash) or --separator "$(printf '\t')".
Trim stray whitespace from the flag value.
For multi-character delimiters, preprocess the data (e.g. sed 's/||/,/g') before piping to gum table.

Example fix

// before
gum table -s '\t' data.csv
// after
gum table -s $'\t' < data.csv

Defensive patterns

Strategy: validation

Validate before calling

sep=';'
if [ ${#sep} -ne 1 ]; then echo "separator must be 1 char" >&2; exit 1; fi
gum table -s "$sep" < data.csv

Try / catch

if ! gum table -s "$sep" < data.csv 2>err.log; then echo "bad separator: $(cat err.log)" >&2; fi

Prevention

Count the separator length before passing it
Use $'\t' for a literal tab, not the two-char string '\t'
Preprocess multi-char delimiters with sed/awk before gum table

When it happens

Trigger: `gum table -s ';'` is fine, but `gum table -s ''` (empty), `gum table -s '\t'` (literal backslash-t, 2 chars), or `gum table -s ',,'` all trigger the error.

Common situations: Wanting a tab separator but passing the two-character literal '\t' instead of a real tab; accidental whitespace in the flag value; passing multi-char sequences like '||'.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of charmbracelet/gum@4d089f9550 (2026-08-31). Data as JSON: /api/errors/1b0b01eab43748a8. Report an issue: GitHub.