jackc/pgx · error

cannot find encode plan

Error message

cannot find encode plan

What it means

Map.Encode guard: no encode plan could be produced for the given OID + format code + Go value combination — the value's Go type has no registered codec mapping to that PostgreSQL type in that format. The unsupported (oid, format, type) triple is the faulty input; the more specific error is normally wrapped in an EncodeError carrying the type and OID.

Solutions

1. Pass a Go value whose type is registered for the parameter's PostgreSQL type
2. Register a custom codec/map for the type via pgtype.Map
3. Check for mismatched placeholder types in the query vs the arguments

When it happens

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

Appendix: source

Thrown at pgtype/pgtype.go:1989

// (nil, nil). The caller of Encode is responsible for writing the correct NULL value or the length of the data
// written.
func (m *Map) Encode(oid uint32, formatCode int16, value any, buf []byte) (newBuf []byte, err error) {
	if isNil, callNilDriverValuer := isNilDriverValuer(value); isNil {
		if callNilDriverValuer {
			newBuf, err = (&encodePlanDriverValuer{m: m, oid: oid, formatCode: formatCode}).Encode(value, buf)
			if err != nil {
				return nil, newEncodeError(value, m, oid, formatCode, err)
			}

			return newBuf, nil
		} else {
			return nil, nil
		}
	}

	plan := m.PlanEncode(oid, formatCode, value)
	if plan == nil {
		return nil, newEncodeError(value, m, oid, formatCode, errors.New("cannot find encode plan"))
	}

	newBuf, err = plan.Encode(value, buf)
	if err != nil {
		return nil, newEncodeError(value, m, oid, formatCode, err)
	}

	return newBuf, nil
}

// SQLScanner returns a database/sql.Scanner for v. This is necessary for types like Array[T] and Range[T] where the
// type needs assistance from Map to implement the sql.Scanner interface. It is not necessary for types like Box that
// implement sql.Scanner directly.
//
// This uses the type of v to look up the PostgreSQL OID that v presumably came from. This means v must be registered
// with m by calling RegisterDefaultPgType.
func (m *Map) SQLScanner(v any) sql.Scanner {
	if s, ok := v.(sql.Scanner); ok {

View on GitHub (pinned to ec1a0befd2)