jackc/pgx · error

invalid tsvector binary format: lexeme

Error message

invalid tsvector binary format: lexeme %d positions: %w

What it means

After reading the packed positions of lexeme %d in a binary tsvector, the reader errored (truncated position data). The allocation was bounded, but the message did not contain all declared positions.

Solutions

1. Fail the scan; position data is incomplete
2. Verify the binary payload comes from a real PostgreSQL server
3. Check for truncation in transit

When it happens

Trigger: Thrown at pgtype/tsvector.go:226 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jackc/pgx@ec1a0befd2 (2026-08-04). Data as JSON: /api/errors/34aeb7c5bc92dbd4. Report an issue: GitHub.

Appendix: source

Thrown at pgtype/tsvector.go:226

		numPositions := int(r.Uint16())
		if err := r.Err(); err != nil {
			return fmt.Errorf("invalid tsvector binary format: lexeme %d: %w", i, err)
		}

		// Each packed position is weight (2 bits) | position (14 bits). numPositions came from a
		// uint16, so it cannot ask for an unreasonable allocation here.
		if numPositions > 0 {
			lexeme.Positions = make([]TSVectorPosition, numPositions)
			for pos := range numPositions {
				packed := r.Uint16()
				lexeme.Positions[pos] = TSVectorPosition{
					Position: packed & 0x3FFF,
					Weight:   tsvectorWeightFromBinary(packed >> 14),
				}
			}
			if err := r.Err(); err != nil {
				return fmt.Errorf("invalid tsvector binary format: lexeme %d positions: %w", i, err)
			}
		}

		tsv.Lexemes[i] = lexeme
	}

	if err := r.Finish(); err != nil {
		return fmt.Errorf("tsvector: %w", err)
	}
	tsv.Valid = true

	return scanner.ScanTSVector(tsv)
}

var tsvectorLexemeReplacer = strings.NewReplacer(
	`\`, `\\`,
	`'`, `\'`,
)

View on GitHub (pinned to ec1a0befd2)