jackc/pgx · error

failed to encode args

Error message

failed to encode args[%d]: %w

What it means

ExtendedQueryBuilder.Build failed to encode an argument at index %d when no statement description exists (QueryExecModeExec-style path, text format). The underlying pgtype encoding error is wrapped; the argument's Go type could not be converted to a text-format parameter.

Solutions

1. Check the type of the failing argument (index given in the message) and register a codec for it if custom
2. Wrap the value in a type pgx knows how to encode
3. Unwrap the error for the precise encoding failure reason

When it happens

Trigger: Thrown at extended_query_builder.go:28 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/a73d1bfe645bb49a. Report an issue: GitHub.

Appendix: source

Thrown at extended_query_builder.go:28

// ExtendedQueryBuilder is used to choose the parameter formats, to format the parameters and to choose the result
// formats for an extended query.
type ExtendedQueryBuilder struct {
	ParamValues     [][]byte
	paramValueBytes []byte
	ParamFormats    []int16
	ResultFormats   []int16
}

// Build sets ParamValues, ParamFormats, and ResultFormats for use with *PgConn.ExecParams or *PgConn.ExecPrepared. If
// sd is nil then QueryExecModeExec behavior will be used.
func (eqb *ExtendedQueryBuilder) Build(m *pgtype.Map, sd *pgconn.StatementDescription, args []any) error {
	eqb.reset()

	if sd == nil {
		for i := range args {
			err := eqb.appendParam(m, 0, pgtype.TextFormatCode, args[i])
			if err != nil {
				err = fmt.Errorf("failed to encode args[%d]: %w", i, err)
				return err
			}
		}
		return nil
	}

	if len(sd.ParamOIDs) != len(args) {
		return fmt.Errorf("mismatched param and argument count")
	}

	for i := range args {
		err := eqb.appendParam(m, sd.ParamOIDs[i], -1, args[i])
		if err != nil {
			err = fmt.Errorf("failed to encode args[%d]: %w", i, err)
			return err
		}
	}

View on GitHub (pinned to ec1a0befd2)