What causes "invalid FilePos GTID (%v): expecting file:pos" in vitessio/vitess?

Supply the position in file:pos form, e.g. mysql-bin.000001:4521

invalid FilePos GTID (%v): expecting file:pos

Error message

invalid FilePos GTID (%v): expecting file:pos

What it means

parseFilePosGTID parses a file-position GTID string of the form 'file:pos' and is registered as a GTID parser. If the string does not split into exactly two colon-separated parts, it is not a valid FilePos GTID and this error names the expected format.

Source

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

*/

package replication

import (
	"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

View on GitHub (pinned to 01a25a7d17)

Solutions

Supply the position in file:pos form, e.g. mysql-bin.000001:4521
Check the source of the GTID string — if it is a real GTID (uuid:sequences), use the matching GTID flavor, not FilePos
Escape/verify no extra colons exist in the file name portion

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

func looksLikeFilePos(s string) bool {
	parts := strings.Split(s, ":")
	if len(parts) != 2 {
		return false
	}
	_, err := strconv.ParseUint(parts[1], 0, 64)
	return err == nil
}

Try / catch

gtid, err := mysql.ParseFilePosGTIDSet(input)
if err != nil {
	if strings.Contains(err.Error(), "expecting file:pos") {
		// not a FilePos GTID; detect flavor or fix the input format
	}
	return err
}

Prevention

Store positions strictly as file:pos, never a bare binlog filename
Do not paste MySQL/MariaDB UUID-style GTIDs where file:pos is expected — use the right flavor
Trim whitespace and verify no extra ':' segments before parsing

When it happens

Trigger: Calling mysql.ParseFilePosGTIDSet (or GTID set parsing that dispatches to this parser) with a string like `mysql-bin.000001` (missing :pos), `a:b:c` (too many parts), or an empty string.

Common situations: Misconfigured replication positions (e.g. passing just a binlog filename instead of file:pos); mixing up GTID formats — pasting a MySQL/MariaDB GTID like `3E11...:1-5` where a file:pos value is expected; users copying values from SHOW BINARY LOG STATUS incorrectly.

Related errors

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