Value Too Long Varchar Truncation

A varchar(N) (character varying(N)) column stores its declared maximum length in the system catalog as pg_attribute.atttypmod, encoded as the character limit plus 4 (the varlena header size, VARHDRSZ), so a varchar(20) column has atttypmod = 24 and the true limit is atttypmod -- 4 = 20. When a value is stored, PostgreSQL enforces that limit and raises error 22001 (string_data_right_truncation) if the value is longer -- it never truncates, because silently losing data would be worse than failing. Crucially, varchar(N), varchar, and text are the same underlying storage with the same performance; the only difference is that varchar(N) carries this length check. That means the N is almost always a guess about future data, and when the guess is wrong the column does not degrade gracefully -- it takes writes down. Widening the limit (increasing N, or converting to varchar/text) only changes the catalog's atttypmod and is therefore a metadata-only operation with no table rewrite; shrinking the limit, by contrast, must scan the table to validate every existing row and will itself raise 22001 if any value is too long.

Free Tier -- Basic Approach

The free diagnosis is reading the error and confirming the column. The 22001 message already names the type and the limit it violated; one catalog lookup confirms which column is declared character varying(20). That is enough to fix the column you were just bitten by.

SELECT a.attname AS column_name,
       format_type(a.atttypid, a.atttypmod) AS declared_type,
       a.atttypmod - 4 AS max_chars
FROM pg_attribute a
WHERE a.attrelid = 'users'::regclass AND a.attname = 'username';

column_name |     declared_type     | max_chars
-------------+-----------------------+-----------
 username    | character varying(20) |        20
(1 row)

Look up the offending column in pg_attribute and render its type with format_type: username is 'character varying(20)' with max_chars = atttypmod -- 4 = 20 -- exactly the cap the error named. The decision it drives is immediate: this one column needs widening.

What it does not tell you is whether any other column is about to fail the same way, which is what the premium audit answers.

The fix is to widen the column to a length that fits the real data. Increasing a varchar limit (or dropping it) is a catalog-only change in modern PostgreSQL -- no table rewrite, no row scan -- so it is fast and safe even on a large table.

ALTER TABLE users ALTER COLUMN username TYPE varchar(64);

ALTER TABLE

INSERT INTO users(username, status, bio) VALUES (repeat('y',25), 'active', 'now fits');

INSERT 0 1

SELECT format_type(atttypid, atttypmod) AS new_type
FROM pg_attribute WHERE attrelid = 'users'::regclass AND attname = 'username';

new_type
-----------------------
 character varying(64)
(1 row)

ALTER TABLE users ALTER COLUMN username TYPE varchar(64) updates only the column's atttypmod; the 'ALTER TABLE' returns immediately with no rewrite. The identical 25-character insert that raised 22001 now returns 'INSERT 0 1', and the column reports its wider declared type, 'character varying(64)'.

Widen to a size that comfortably covers your real maximum, or convert to text and enforce the true limit with a CHECK constraint (see prevention).

Healthy-state proof: a value that used to fail now inserts, the column reports its widened type, and the headroom that was 0 is now comfortably positive -- the landmine is cleared, not just the single row.

INSERT INTO users(username, status, bio) VALUES (repeat('z',30), 'active', 'verify insert');

INSERT 0 1

SELECT format_type(atttypid, atttypmod) AS declared_type
FROM pg_attribute WHERE attrelid = 'users'::regclass AND attname = 'username';

declared_type
-----------------------
 character varying(64)
(1 row)

SELECT (atttypmod - 4) AS declared_limit,
       (SELECT max(length(username)) FROM users) AS max_observed,
       (atttypmod - 4) - (SELECT max(length(username)) FROM users) AS headroom
FROM pg_attribute WHERE attrelid = 'users'::regclass AND attname = 'username';

declared_limit | max_observed | headroom
----------------+--------------+----------
             64 |           30 |       34
(1 row)

Insert a 30-character username (well past the old 20-character limit): it returns 'INSERT 0 1'. The column now reports 'character varying(64)', and the headroom calculation -- declared limit (64) minus the longest stored value (30) -- is 34.

A positive, generous headroom is the durable signal that this column is no longer at risk.

📦 Version Matrix (PG 14--18)

The length check and its fix are core character-type behaviour, identical across supported releases. On PostgreSQL 14 through 18 the over-length insert fails with the same 22001 'value too long' error, and after widening the same insert succeeds.

Frequently Asked Questions

References

• Character Types -- character varying(n), char(n), and text
• ALTER TABLE -- ALTER COLUMN ... SET DATA TYPE (rewrite vs metadata-only)
• PostgreSQL Error Codes -- Class 22 (22001 string_data_right_truncation)
• pg_attribute -- atttypmod and column metadata
• Constraints -- CHECK constraints