vitessio/vitess · error

err

Error message

err

What it means

MustDecodeGTID is the panicking variant of DecodeGTID, which parses an encoded GTID string of the form "flavor:value". On any decode failure (missing separator, unknown flavor, bad value) it panics. Use only when the string is known to have been produced by EncodeGTID.

Source

Thrown at go/mysql/replication/gtid.go:110

// a GTID interface value with the correct underlying flavor.
func DecodeGTID(s string) (GTID, error) {
	if s == "" {
		return nil, nil
	}

	parts := strings.SplitN(s, "/", 2)
	if len(parts) != 2 {
		// There is no flavor. Try looking for a default parser.
		return ParseGTID("", s)
	}
	return ParseGTID(parts[0], parts[1])
}

// MustDecodeGTID calls DecodeGTID and panics on error.
func MustDecodeGTID(s string) GTID {
	gtid, err := DecodeGTID(s)
	if err != nil {
		panic(err)
	}
	return gtid
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Use DecodeGTID with error handling for any externally stored or user-supplied string
2. Ensure the string was produced by EncodeGTID (flavor included) rather than a bare value
3. Validate format (split on first ':' and check flavor) before the Must* call

Example fix

// before
gtid := replication.MustDecodeGTID(raw)
// after
gtid, err := replication.DecodeGTID(raw)
if err != nil {
	return vterrors.Wrapf(err, "cannot decode GTID %q", raw)
}

if !strings.Contains(s, ":") {
	return fmt.Errorf("encoded GTID %q missing flavor separator", s)
}

func safeDecodeGTID(s string) (gtid replication.GTID, err error) {
	defer func() {
		if r := recover(); r != nil {
			err = fmt.Errorf("MustDecodeGTID panicked on %q: %v", s, r)
		}
	}()
	return replication.MustDecodeGTID(s), nil
}

When it happens

Trigger: Calling MustDecodeGTID(s) with a string that lacks the "flavor:value" form, contains an unknown flavor prefix, or holds a value invalid for that flavor.

Common situations: Reading GTIDs stored in external stores (etcd, user configs) that were written by older Vitess versions or other tools with a different encoding; hand-edited strings.

Related errors

• panic(err)
• invalid FilePos GTID (%v): expecting file:pos
• invalid FilePos GTID (%v): expecting pos to be an integer
• can't get GTID from binlog event: %v, event data: %#v
• failed to parse pos column: %v

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/f9bd080032b999f7. Report an issue: GitHub.