invalid length for CopyOutResponse.OverallFormat

Error message

invalid length for CopyOutResponse.OverallFormat

What it means

Returned by CopyOutResponse.UnmarshalJSON when the JSON `OverallFormat` field is not exactly one character. The wire field is a single byte (0 = text, 1 = binary), so the JSON form must be a one-char string.

Source

Thrown at pgproto3/copy_out_response.go:90

}

// UnmarshalJSON implements encoding/json.Unmarshaler.
func (dst *CopyOutResponse) UnmarshalJSON(data []byte) error {
	// Ignore null, like in the main JSON package.
	if string(data) == "null" {
		return nil
	}

	var msg struct {
		OverallFormat     string
		ColumnFormatCodes []uint16
	}
	if err := json.Unmarshal(data, &msg); err != nil {
		return err
	}

	if len(msg.OverallFormat) != 1 {
		return errors.New("invalid length for CopyOutResponse.OverallFormat")
	}

	dst.OverallFormat = msg.OverallFormat[0]
	dst.ColumnFormatCodes = msg.ColumnFormatCodes
	return nil
}

View on GitHub (pinned to ec1a0befd2)

Solutions

Use the single-char wire form: "0" (text) or "1" (binary).
Map words to codes: `"text" -> "0"`, `"binary" -> "1"`.
Regenerate fixtures from MarshalJSON output.
Pre-validate the JSON shape before unmarshalling.

Example fix

// before
raw := []byte(`{"OverallFormat":"text","ColumnFormatCodes":[0]}`)
err := json.Unmarshal(raw, &co) // error

// after
raw := []byte(`{"OverallFormat":"0","ColumnFormatCodes":[0]}`)
err := json.Unmarshal(raw, &co)

Defensive patterns

Strategy: validation

Validate before calling

func validateCopyOutOverallFormat(raw []byte) error {
	var probe struct{ OverallFormat string }
	if err := json.Unmarshal(raw, &probe); err != nil { return err }
	if len(probe.OverallFormat) != 1 {
		return fmt.Errorf("OverallFormat must be one char (\"0\"/\"1\"), got %q", probe.OverallFormat)
	}
	return nil
}

Type guard

func isValidCopyOverallFormat(s string) bool {
	return len(s) == 1 && (s == "0" || s == "1")
}

Try / catch

var co pgproto3.CopyOutResponse
if err := json.Unmarshal(raw, &co); err != nil {
    // clarify OverallFormat must be "0"/"1"
    return err
}

Prevention

Emit OverallFormat as "0" (text) or "1" (binary).
Regenerate fixtures from MarshalJSON.
Map words to codes for incoming JSON.

When it happens

Trigger: `json.Unmarshal(data, &copyOut)` where `OverallFormat` has length != 1 — e.g. `{"OverallFormat": "text"}` or `{"OverallFormat": 0}` (number).

Common situations: Fixtures, snapshot tests, or proxy tooling encode OverallFormat as a word or numeric literal. A hand-edited or generated JSON with the field omitted (empty after default) also fails.

Related errors

AI-assisted analysis of jackc/pgx@ec1a0befd2 (2026-08-04). Data as JSON: /data/errors/3b7fb5f83b4f67d0.json. Report an issue: GitHub.