vCard QR code imports with missing or wrong fields

Two causes cover almost all of these: unescaped commas and semicolons inside a value, which split the field, and a missing FN line, which leaves the display name blank. Both fail silently at generation and only appear when someone saves the contact.

1. Unescaped punctuation

Inside a vCard value, four characters must be backslash-escaped:

,   ;   \   and a newline, written \n

A job title of Director, Engineering written literally becomes two values, and most address books show only Director. An address containing semicolons is worse, because ADR is itself semicolon-structured.

2. Missing FN

N is the structured name (family;given;middle;prefix;suffix — all four semicolons required, even when empty). FN is the display name, and many address books use it exclusively.

Omit FN and the contact imports with a blank name. This is the single most common vCard QR defect.

3. Line folding

The spec folds lines longer than 75 octets by inserting CRLF followed by a single space. Strict parsers reject unfolded long lines; lenient ones accept them. A long note or a long URL is where this bites.

4. Version mismatch

vCard 4.0 writes phone types as TEL;TYPE="cell":; 3.0 writes TEL;TYPE=CELL:. A 3.0 parser reading 4.0 syntax may drop the type or the whole line. Use 3.0 for QR codes — it is universally supported and the extra 4.0 properties rarely survive import anyway.

5. Fields the phone simply ignores

Address books drop properties they do not recognise. X- extensions, KIND, GENDER, ANNIVERSARY and most 4.0 additions usually vanish. They still cost bytes, which pushes the version up and makes the code harder to scan — so removing them improves the code twice.

6. A photo

PHOTO;ENCODING=b with base64 image data cannot fit: images are kilobytes and the maximum QR payload is 2,953 bytes. If the generator allowed it, the code will be enormous and unscannable. Use PHOTO;VALUE=URI: pointing at a hosted image.

The diagnostic

Decode your own code with our scanner and read the raw vCard text. A split value or a missing FN is obvious immediately.

FAQ

Why does my contact import with no name?

The vCard is missing the FN (formatted name) line. N alone is not enough — many address books display FN exclusively.

Why is my job title cut off at the comma?

Commas inside a vCard value must be backslash-escaped. Unescaped, they split the value and most parsers keep only the first part.

Should I use vCard 3.0 or 4.0 in a QR code?

3.0. It is universally supported by phone cameras and scanner apps, and 4.0's extra properties are usually discarded on import anyway.

Can I include a photo in a vCard QR code?

No. Base64 image data runs to kilobytes against a 2,953-byte maximum. Link to a hosted image with PHOTO;VALUE=URI: instead.