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.