jackc/pgx · error

unknown format code

Error message

unknown format code %d

What it means

The multirange scan plan dispatches on the result format code captured at plan time, handling only binary and text. This is the default-branch guard: it fires when the stored format code is neither known value, which in practice means a corrupt format code reached the plan from the connection or query configuration.

Solutions

1. Check query/result format configuration for invalid format codes
2. Report as a driver bug since PostgreSQL only defines text and binary formats
3. Upgrade pgx to the latest version

When it happens

Trigger: Thrown at pgtype/multirange.go:301 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/a4f828e5ff1d3de5. Report an issue: GitHub.

Appendix: source

Thrown at pgtype/multirange.go:301

func (spac *scanPlanMultirangeCodec) Scan(src []byte, dst any) error {
	c := spac.multirangeCodec
	m := spac.m
	oid := spac.oid
	formatCode := spac.formatCode

	multirange := dst.(MultirangeSetter)

	if src == nil {
		return multirange.ScanNull()
	}

	switch formatCode {
	case BinaryFormatCode:
		return c.decodeBinary(m, oid, src, multirange)
	case TextFormatCode:
		return c.decodeText(m, oid, src, multirange)
	default:
		return fmt.Errorf("unknown format code %d", formatCode)
	}
}

func (c *MultirangeCodec) DecodeDatabaseSQLValue(m *Map, oid uint32, format int16, src []byte) (driver.Value, error) {
	if src == nil {
		return nil, nil
	}

	switch format {
	case TextFormatCode:
		return string(src), nil
	case BinaryFormatCode:
		buf := make([]byte, len(src))
		copy(buf, src)
		return buf, nil
	default:
		return nil, fmt.Errorf("unknown format code %d", format)
	}

View on GitHub (pinned to ec1a0befd2)