jackc/pgx · error

invalid tsvector format: lexeme must start with a single…

Error message

invalid tsvector format: lexeme must start with a single quote

What it means

Text tsvector parser guard in consumeLexeme: a quoted lexeme must begin with an opening single quote, but the first consumed character was something else (or input ended). Applies when parsing lexemes that require quoting (spaces, quotes, special characters).

Solutions

1. Quote lexemes containing special characters: 'won''t' style with escaped quotes
2. Fix hand-built tsvector strings to follow PostgreSQL's text format
3. Let PostgreSQL produce the tsvector (to_tsvector) instead of constructing text manually

When it happens

Trigger: Thrown at pgtype/tsvector.go:366 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/d361e3dd0c5bc5b5. Report an issue: GitHub.

Appendix: source

Thrown at pgtype/tsvector.go:366

	if p.pos >= len(p.str) {
		return 0, true
	}
	b := p.str[p.pos]
	p.pos++
	return b, false
}

func (p *tsvectorParser) consumeSpaces() {
	for !p.atEnd() && p.peek() == ' ' {
		p.consume()
	}
}

// consumeLexeme consumes a single-quoted lexeme, handling single quotes and backslash escapes.
func (p *tsvectorParser) consumeLexeme() (string, error) {
	ch, end := p.consume()
	if end || ch != '\'' {
		return "", fmt.Errorf("invalid tsvector format: lexeme must start with a single quote")
	}

	var buf strings.Builder
	for {
		ch, end := p.consume()
		if end {
			return "", fmt.Errorf("invalid tsvector format: unterminated quoted lexeme")
		}

		switch ch {
		case '\'':
			// Escaped quote ('') — write a literal single quote
			if !p.atEnd() && p.peek() == '\'' {
				p.consume()
				buf.WriteByte('\'')
			} else {
				// Closing quote — lexeme is complete
				return buf.String(), nil

View on GitHub (pinned to ec1a0befd2)