22001

At a glance

22001 is string_data_right_truncation. The fixed varchar path reports the declared character width, while hstore and varbit have separate variants.

The shared case creates varchar_limits(value varchar(3)), inserts 'too-long' to capture 22001, inserts 'ok' as the repair, and selects the stored value. Send these statements separately in autocommit: the trigger is expected to fail before the repair statement runs. The runner owns object cleanup after the case.

CREATE TABLE varchar_limits (value varchar(3));
INSERT INTO varchar_limits VALUES ('too-long');
INSERT INTO varchar_limits VALUES ('ok');
SELECT value FROM varchar_limits;

Calibration observed character varying(3) rejecting an overlong value with value too long for type character varying(3); the corrected value ok succeeded and both runner autocommit sessions returned to IDLE.

Messages

The fixed character and varchar guards raise ERROR with primary templates value too long for type character(%d) and value too long for type character varying(%d). The hstore and varbit paths use their own primary templates (string too long for hstore key, string too long for hstore value, and bit string too long for type bit varying(%d)). These source groups provide no separate DETAIL or HINT. The selected runtime observed only the varchar template shown above.

Meaning

22001 is raised when a value cannot satisfy a string type's length contract. PostgreSQL measures character(n) and character varying(n) in characters, so a message such as value too long for type character(%d) points to the typmod shown in the response. The fixed varchar.c path is the server-side check; hstore keys/values and bit strings have separate source paths and messages.

The boundary also depends on how the value reaches the type. The varchar() and bpchar() functions receive an isExplicit flag: an assignment/input conversion rejects excess non-space characters, while an explicit cast to the bounded type can truncate according to PostgreSQL's character-type rules; excess trailing spaces are treated differently from non-space characters. Make that choice explicit before changing storage or input validation.

Diagnosis

Capture schema_name, table_name, column_name, datatype_name, routine, and the full primary message. Confirm the target type and typmod from the catalog, then measure the actual value in characters rather than bytes. Check whether the value was inserted/assigned, explicitly cast, or passed through an hstore/bit path; those paths do not share identical truncation behavior.

For the common varchar case, compare the non-space suffix with the declared width. A value that only exceeds the width through trailing spaces can follow the character-type truncation rule, while meaningful non-space data should be treated as a rejected contract. The fixed source message is a type-width diagnosis, not a general encoding or network failure.

Response

Choose the repair that preserves the data contract: validate and reject overlong input, deliberately widen the column/type, or explicitly cast only when truncation is an accepted business rule. Record the original value and target typmod before truncating; silently cutting identifiers, keys, or audit text can create a different row than the caller intended. The frozen case used autocommit, so the failed statement left the session IDLE; inside an explicit transaction, roll back the transaction or use ROLLBACK TO SAVEPOINT for a savepoint created before the statement before retrying the corrected value. After changing the input or schema, re-run the conversion and verify the stored character length.

Versions

The locked catalogue records this condition from 7.4 in the listed formal snapshots and 19beta3; fixed source coverage is PostgreSQL 18.6.

Related

22003 for numeric/range overflow, 22007 for datetime format errors, and 22004 for a separate NULL contract.

Sources

The fixed character(n) check is varchar.c#L300-L313, and the character varying(n) check is varchar.c#L633-L640. PostgreSQL 18's character types document character-count limits, trailing-space behavior, and explicit casts. The structured evidence record pins the source SHA and keeps hstore/varbit variants separate.

Source evidence

Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.

• src/backend/utils/errcodes.txt · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• raw/calls/REL_18_6.jsonl · ·
• src/backend/utils/adt/varchar.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/utils/adt/varchar.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• contrib/hstore/hstore_io.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• src/backend/utils/adt/varbit.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• verify/cases/22001/snippets.json · ·

Message templates

value too long for type character(%d)

value too long for type character varying(%d)

string too long for hstore key

string too long for hstore value

bit string too long for type bit varying(%d)

Reproduction & repair cases

Recorded runtime evidence

{
  "sqlstate": "22001",
  "status_after_repair": "IDLE"
}

{
  "sqlstate": "22001",
  "status_after_repair": "IDLE"
}