What causes "invalid FilePos GTID (%v): expecting pos to be an integer" in vitessio/vitess?

Replace the position with a single plain integer, e.g. mysql-bin.000001:4521

invalid FilePos GTID (%v): expecting pos to be an integer

Error message

invalid FilePos GTID (%v): expecting pos to be an integer

What it means

After splitting a FilePos GTID on ':', the position part must parse as an unsigned 64-bit integer via strconv.ParseUint (base 0). If it does not, the string is rejected with this error even though the overall file:pos shape was correct.

Source

Thrown at go/mysql/replication/filepos_gtid.go:38

	"fmt"
	"strconv"
	"strings"
)

// FilePosFlavorID is the string identifier for the filePos flavor.
const FilePosFlavorID = "FilePos"

// parsefilePosGTID is registered as a GTID parser.
func parseFilePosGTID(s string) (GTID, error) {
	// Split into parts.
	parts := strings.Split(s, ":")
	if len(parts) != 2 {
		return nil, fmt.Errorf("invalid FilePos GTID (%v): expecting file:pos", s)
	}

	pos, err := strconv.ParseUint(parts[1], 0, 64)
	if err != nil {
		return nil, fmt.Errorf("invalid FilePos GTID (%v): expecting pos to be an integer", s)
	}

	return FilePosGTID{
		File: parts[0],
		Pos:  pos,
	}, nil
}

// ParseFilePosGTIDSet is registered as a GTIDSet parser.
func ParseFilePosGTIDSet(s string) (GTIDSet, error) {
	gtid, err := parseFilePosGTID(s)
	if err != nil {
		return nil, err
	}
	return gtid.(FilePosGTID), err
}

// FilePosGTID implements GTID.

View on GitHub (pinned to 01a25a7d17)

Solutions

Replace the position with a single plain integer, e.g. mysql-bin.000001:4521
Remove ranges (1-5) or non-numeric suffixes — file:pos accepts one position only
Verify the position fits in uint64 (no values above 18446744073709551615)

Example fix

// before
gtid, err := mysql.ParseFilePosGTIDSet("mysql-bin.000001:1-5")
// after
gtid, err := mysql.ParseFilePosGTIDSet("mysql-bin.000001:4521")

Defensive patterns

Strategy: validation

Validate before calling

func posIsSingleUint64(s string) bool {
	parts := strings.Split(s, ":")
	if len(parts) != 2 {
		return false
	}
	pos, err := strconv.ParseUint(parts[1], 0, 64)
	return err == nil && pos >= 0 && !strings.Contains(parts[1], "-")
}

Try / catch

gtid, err := mysql.ParseFilePosGTIDSet(input)
if err != nil {
	if strings.Contains(err.Error(), "pos to be an integer") {
		// strip ranges/typos or reject: a single numeric position is required
	}
	return err
}

Prevention

Never pass binlog ranges (file:1-5) as a position — pick a single position
Validate the position with strconv.ParseUint before parsing
Double-check manual replication setup values for typos and overflow

When it happens

Trigger: Calling ParseFilePosGTIDSet with values like `mysql-bin.000001:abc`, `mysql-bin.000001:-5`, `mysql-bin.000001:99999999999999999999999` (overflow beyond uint64), or a sequence list like `mysql-bin.000001:1-5`.

Common situations: Copy/paste of a binlog event range (file:1-5) into a position field expecting a single position; typos in manual replication setup; confusing MySQL GTID sequence notation with file/pos notation.

Related errors

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