macaddr8 data out of range to convert to macaddr

Symptoms

A statement failed with SQLSTATE 22003 (numeric_value_out_of_range), reported at severity ERROR. This is a Data Exception condition: PostgreSQL emits the message macaddr8 data out of range to convert to macaddr.

• The client receives SQLSTATE 22003 (numeric value out of range).
• The operation is rejected at ERROR level; the statement does not complete.

What the server log shows

ERROR:  macaddr8 data out of range to convert to macaddr
HINT:  Only addresses that have FF and FE as values in the 4th and 5th bytes from the left, for example xx:xx:xx:ff:fe:xx:xx:xx, are eligible to be converted from macaddr8 to macaddr.

Why PostgreSQL raises this

Class 22 (Data Exception) is raised at run time when a value cannot be represented, converted, or processed by the requested type or function — bad input syntax, out-of-range values, or invalid arguments.

As described in PostgreSQL’s Chapter 8 Data Types and Appendix A (PostgreSQL Error Codes), SQLSTATE 22003 carries the condition name numeric_value_out_of_range in class Data Exception. (Paraphrased — see the linked reference for the exact wording.)

Common causes

• A literal or parameter does not match the target type’s input format.
• A value exceeds the range or length the type allows.
• A function received an argument outside its valid domain.
• An encoding, cast, or format conversion failed.

How to fix it

1. Validate and sanitize the input value before sending it.
2. Cast explicitly to the intended type and confirm the format.
3. Widen the column/type or clamp the value to the supported range.
4. Reproduce with the exact literal to see which value is rejected.

Version applicability

This message text is present in PostgreSQL 15, 16, 17, 18.

Related & next steps

• SQLSTATE 22003 — Numeric Value Out Of Range (full reference)
• PostgreSQL error code index

Reference: PostgreSQL Chapter 8 Data Types.