benbjohnson/litestream · error

invalid txid format

Error message

invalid txid format

What it means

Error from txidVar.Set, the flag.Value used for -txid command-line flags, when ltx.ParseTXID cannot parse the argument. Fires when a user passes a flag value that is not a valid 8-character hexadecimal TXID (e.g. 'abc' or '123z').

Source

Thrown at cmd/litestream/main.go:2172

	return s
}

// txidVar allows the flag package to parse index flags as hex-formatted TXIDs
type txidVar ltx.TXID

// Ensure type implements interface.
var _ flag.Value = (*txidVar)(nil)

// String returns an 8-character hexadecimal value.
func (v *txidVar) String() string {
	return ltx.TXID(*v).String()
}

// Set parses s into an integer from a hexadecimal value.
func (v *txidVar) Set(s string) error {
	txID, err := ltx.ParseTXID(s)
	if err != nil {
		return fmt.Errorf("invalid txid format")
	}
	*v = txidVar(txID)
	return nil
}

// levelAll is a sentinel value indicating all compaction levels should be shown.
const levelAll = -1

// levelVar allows the flag package to parse compaction level flags.
// Accepts integers 0-9 or "all" for all levels.
type levelVar int

var _ flag.Value = (*levelVar)(nil)

func (v *levelVar) String() string {
	if *v == levelAll {
		return "all"
	}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Pass the TXID as bare uppercase or lowercase hexadecimal, e.g. `0000000000000042`.
2. Strip any `0x` prefix or surrounding quotes/whitespace.
3. Get the exact TXID string from `litestream ltx` output and reuse it verbatim.

Example fix

// before
litestream ltx -txid 0x42
// after
litestream ltx -txid 0000000000000042

// Validate hex TXID before passing to the CLI
if _, err := strconv.ParseUint(strings.TrimPrefix(txid, "0x"), 16, 64); err != nil {
    return fmt.Errorf("not a hex txid: %q", txid)
}

if err := cmd.Run(); err != nil {
    if strings.Contains(err.Error(), "invalid txid format") {
        // normalize to bare hex and retry
    }
}

When it happens

Trigger: Running `litestream ltx -txid <value>` where value is not a valid hexadecimal TXID (e.g. decimal digits like `123456789` are fine only if hex-valid; values with non-hex characters like `0x` prefix, spaces, or `abcg`).

Common situations: Copy-pasting a TXID with a `0x` prefix from a debugger; passing a decimal TXID string from another tool; including whitespace or quoting artifacts.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• invalid level: must be 0-%d or "all"
• level must be between 0 and %d
• config file not found
• invalid -timestamp, must specify in ISO 8601 format (e.g. 20
• database path required

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/1a411fdbd13d1c6f. Report an issue: GitHub.