Oracle Error ORA-12899

Error code

ORA-12899

Product

Oracle Database

Versions

Oracle Database 19c, 21c, 23ai and 26ai (same wording in every release)

Category

Data Types & Conversion

Last reviewed

24 October 2026

What it means

ORA-12899 means an INSERT or UPDATE tried to store a string that is longer than the character column (VARCHAR2, CHAR, NVARCHAR2 or NCHAR) allows; the message names the column, the actual length and the maximum.

Each character column has a maximum length, and Oracle rejects the statement rather than cut the value. The message gives you everything you need: the column as schema, table and column, the length of the value and the limit. Oracle's reference adds the detail that matters most: the lengths are in characters if the column uses character length semantics, and otherwise in bytes.

That is why accented or non-Latin text fails sooner than you expect: in a database with a multibyte character set such as AL32UTF8, one character can take two to four bytes, so VARCHAR2(20 BYTE) may hold far fewer than 20 characters. The default is BYTE semantics (NLS_LENGTH_SEMANTICS = BYTE). The current reference also notes that when actual equals maximum, the converted value did not fit and more remained to be stored.

Common causes

• The value is simply longer than the column: a long name, address, comment or URL.
• The column uses BYTE semantics and the text has multibyte characters (accents, Arabic, Chinese, emoji), so its length in bytes exceeds the limit even though the character count fits.
• Data moved from a single-byte character set database (or a column with CHAR semantics) to an AL32UTF8 one expands in bytes.
• A load or INSERT ... SELECT maps a wide source column into a narrower target column, or concatenates values without trimming.
• Application validation counts characters while the column counts bytes, so values pass the form and fail in the database.

Diagnose it

Read-only These queries only read the data dictionary (USER_, ALL_ and DBA_ views) and dynamic performance views (V$). They do not change data, privileges or settings, so they are safe to run first. DBA_ and V$ views need the matching privileges.

SELECT column_name, data_type, char_length, data_length, char_used
FROM all_tab_columns
WHERE owner = 'SHOP'
  AND table_name = 'CUSTOMERS'
  AND column_name = 'CITY';

SELECT customer_id, city, LENGTH(city) AS chars, LENGTHB(city) AS bytes
FROM shop.customers_staging
WHERE LENGTHB(city) > 20
ORDER BY bytes DESC;

SELECT parameter, value
FROM nls_database_parameters
WHERE parameter IN ('NLS_CHARACTERSET', 'NLS_NCHAR_CHARACTERSET', 'NLS_LENGTH_SEMANTICS');

How to fix it

Each fix is labelled with what it changes. Try read-only checks and the least invasive fix first, and test changes outside production.

ALTER TABLE shop.customers MODIFY (city VARCHAR2(100 CHAR));

INSERT INTO shop.customers (customer_id, city)
SELECT customer_id, SUBSTR(city, 1, 20)
FROM shop.customers_staging;

Examples

A city name longer than the column

Not reproduced here: no Oracle Database is installed for this site. The result shows the message format documented in Oracle's error reference (same in 26ai, 21c and 19c) with this example's names and lengths filled in; the table is assumed to be in schema SHOP.

CREATE TABLE customers (
    customer_id NUMBER PRIMARY KEY,
    city        VARCHAR2(20)
);

INSERT INTO customers (customer_id, city)
VALUES (1, 'Saint-Etienne-du-Rouvray');  -- 24 characters

ORA-12899: value too large for column "SHOP"."CUSTOMERS"."CITY" (actual: 24, maximum: 20)

Multibyte text in a BYTE column

Not reproduced here: no Oracle Database is installed for this site. The message format is from Oracle's error reference; the lengths are in bytes because the column uses BYTE semantics, as the reference explains. The Cyrillic characters are written with UNISTR to keep this page plain ASCII. Declaring label VARCHAR2(10 CHAR) stores the six characters.

-- AL32UTF8 database, VARCHAR2(10 BYTE); each of these 6 characters takes 2 bytes
CREATE TABLE products (
    sku   VARCHAR2(20),
    label VARCHAR2(10 BYTE)
);

INSERT INTO products (sku, label)
VALUES ('A-100', UNISTR('\0416\0443\0440\043D\0430\043B'));

ORA-12899: value too large for column "SHOP"."PRODUCTS"."LABEL" (actual: 12, maximum: 10)

How to prevent it

Declare character columns with explicit CHAR semantics (VARCHAR2(100 CHAR)) in databases that store multilingual text, and size them for real data rather than the shortest example. Keep application validation in the same unit as the column.

Before a load or a character set migration, compare LENGTH and LENGTHB of the source with the target limits, and decide up front whether long values should be rejected, truncated or the column widened. See SQL data types explained.

Common questions

Learn more on CodeWithSQL

• SQL data types explained
• LENGTH function
• SUBSTRING function

Official documentation

• ORA-12899 (Oracle Database Error Messages)
• NLS_LENGTH_SEMANTICS (Oracle Database Reference 19c)
• Data Types, including VARCHAR2 limits (Oracle SQL Language Reference 19c)
• ALTER TABLE (Oracle SQL Language Reference 19c)

Last technically reviewed 24 October 2026; examples and diagnostics run on Oracle Database Error Messages reference (26ai, 21c and 19c); not run locally. Messages and explanations follow Oracle's Database Error Messages reference; no Oracle Database was available, so the examples were not run locally.