STRING_TOO_LONG: data value too large

The platform refuses partial writes — if your value is 256 characters and the field is 255, the entire DML throws. The error message includes the field name and (usually) the maximum length, so the diagnosis is mechanical.

A common surprise: byte length vs character length

Salesforce field limits are measured in characters, not bytes — but Multi-Currency, formula-derived strings, and concatenated values can each contribute differently. 255 characters means 255 characters whether they're ASCII, accented Latin, or emoji. Database storage is UTF-8, so emojis take more bytes — but the limit check is in characters, so this doesn't usually bite.

The case it does bite: SOAP API integrations whose XML envelope counts character-encoded entities (& is 5 characters in transit, 1 in the field). Most modern SDKs handle this; legacy ones occasionally don't.

The defensive Apex pattern

Truncate before insert with a helper:

public static String safeTruncate(String value, Integer max) {
    if (value == null) return null;
    if (value.length() <= max) return value;
    return value.substring(0, max);
}

Account a = new Account(
    Name = 'Acme',
    Description = safeTruncate(longInputDescription, 255)
);
insert a;

For a more user-friendly approach, log a warning when truncation happens — silent truncation is a data-quality bug waiting to be discovered.

When to change the field

If the truncation is happening systematically (every record from one source is too long), the field length is wrong, not the data. Increase it:

• Standard fields have fixed lengths set by Salesforce.
• Custom Text fields go up to 255 chars.
• Custom Long Text Area fields go up to 131,072 chars (128 KB).
• Custom Rich Text Area fields go up to 131,072 chars (with formatting).

If you need more than 255 chars, change the field type to Long Text Area. There's a one-time migration: existing records are truncated to fit, but you can Database.queryAll in batches and re-source from the original system.

Find the offender

If your error doesn't name the field, log all field values being written:

} catch (DmlException e) {
    System.debug('Error fields: ' + e.getDmlFieldNames(0));
    System.debug('Error message: ' + e.getDmlMessage(0));
    // The field names array tells you which fields the platform flagged
}

getDmlFieldNames(0) returns the API names of the fields that caused the failure on row 0. For STRING_TOO_LONG, this is your culprit.