Common vCard (.vcf) Import Errors and How to Fix Them — A Developer's Deep-Dive

A vCard file looks like the simplest thing in the world:

BEGIN:VCARD VERSION:3.0 FN:Jane Doe END:VCARD

And yet — hour by hour, day by day — developers find themselves staring at import errors from Gmail, Outlook, iOS, macOS, Android, HubSpot, Salesforce, and dozens of other contact managers. The vCard spec is broad, inconsistently implemented, and often surprisingly unforgiving.

This article is the definitive guide to diagnosing and fixing vCard import errors, with specific patterns, examples, and compatibility notes across major platforms. If your .vcf files “look fine” but refuse to import, this guide will help you pinpoint the problem.

1. Missing or Incorrect BEGIN/END Wrappers

Every vCard must be wrapped in:

BEGIN:VCARD END:VCARD

Common mistakes

Missing the END:VCARD line

Lowercase or mixed-case wrappers

Extra whitespace after the identifier

Hidden characters or non-breaking spaces at the end

Why this causes imports to fail

Importers rely on these markers to parse the boundaries of the record. Missing one will cause the importer to reject the entire file or silently truncate data.

How to fix

Ensure lines are exact, no trailing spaces

Normalize line endings

Programmatically verify top and bottom lines

2. The File Has the Wrong Encoding (The Silent Killer)

Encoding issues account for nearly one-third of all import failures.

Problem

Some environments output .vcf files in:

Latin-1

Windows-1252

Shift-JIS

Mixed encodings

UTF-8 without BOM

UTF-8 with BOM (which breaks some importers)

Symptoms

Non-ASCII characters appear as �

Gmail rejects the file as “invalid”

iOS silently fails to import

Outlook dangerously truncates the file

How to fix

Standardize encoding to UTF-8 without BOM

Escape characters per vCard spec (e.g., \n, ,, ;)

Validate via a parser (CorrectVCF will show where the error is)

3. Missing FN or N Fields (Google Contacts Hates This) Problem

Developers often assume a name is optional.

Reality

Most importers require at least one of:

FN:Full Name N:Last;First;;;

Symptoms

Google Contacts gives “We couldn’t import some contacts”

iOS creates a blank, nameless card

Outlook rejects the vCard entirely

How to fix

Always include both fields

Ensure they’re not empty

Escape special characters correctly

4. Incorrectly Formatted Address Fields

The vCard ADR: property is one of the most rigid parts of the spec.

Correct seven-field format ADR;TYPE=home:;;123 Main St;Austin;TX;78701;USA

Common errors

Using commas instead of semicolons

Missing placeholders, such as:

ADR:123 Main St;Austin;TX ← Invalid

Combining city + state into one field

Using an address format specific to one country

Symptoms

Google Contacts drops the entire address

iOS displays “No Address”

Outlook imports address but breaks into incorrect components

How to fix

Always include all semicolons

Preserve field positions even when empty

Test with At least two importers

5. Deprecated Parameter Types (Especially TEL & EMAIL)

Older vCard generators may output:

TEL;CELL:555-123-4567

Modern format is:

TEL;TYPE=cell:555-123-4567

Common problems

Clients misinterpret property types

Work numbers appear as home numbers

Labels are lost on import

Some clients reject nonstandard parameter capitalization

How to fix

Use TYPE= syntax exclusively

Lowercase values for consistency

Don’t stack types incorrectly (TYPE=work,voice is OK; TYPE=work;voice is not)

6. Multiple Contacts Not Separated Correctly

When exporting multiple contacts, each must be self-contained:

BEGIN:VCARD … END:VCARD BEGIN:VCARD … END:VCARD

Common mistakes

Missing END:VCARD

Inserting VERSION outside of a block

Concatenating two contacts inside one block

Accidental trailing characters between contacts

Symptoms

Imports only the first contact

Importer crashes silently

Mis-merged contacts (rare but dangerous)

How to fix

Programmatically wrap each record

Use a validator on multi-contact files

Normalize whitespace boundaries

7. Line Folding Errors (RFC 6350 Strictness)

Long vCard lines can be “folded” with a space at the beginning of the continuation line:

NOTE:This is a very long note that requires folding.

But many importers:

Accept folded lines

Reject them

Mis-handle them

Unfold them incorrectly

Common mistakes

Folding without a leading space

Folding mid-UTF-8 character

Line wrapping with tabs instead of spaces

Symptoms

Outlook shows truncated fields

Gmail drops the entire note

iOS imports but adds stray whitespace

How to fix

Avoid line folding if possible (modern systems allow long lines)

If necessary, follow RFC rules exactly

Run output through a linter

8. BOM (Byte Order Mark) at Start of File

Some libraries output UTF-8 with BOM:

BEGIN:VCARD

Importers treat this as a corruption.

Symptoms

Gmail refuses import

iOS shows weird invisible characters

Outlook ignores the file entirely

How to fix

Strip BOM from output

Ensure UTF-8 without BOM in your export code

Validate the first 3 bytes of the file

9. Incorrect Date Formats (BDAY & ANNIVERSARY)

Many developers output human-readable dates:

BDAY:04/23/1985 ← Wrong

Correct format:

BDAY:1985-04-23

Symptoms

Birthday not imported

Outlook uses wrong year

Google Contacts quietly drops it

How to fix

Enforce YYYY-MM-DD

Do not localize date formats

Strip time components unless specifically needed

10. Invalid Photo Embedding or Image Types

vCard allows either Base64 or URL-based photos:

Valid embedding: PHOTO;ENCODING=b;TYPE=JPEG:/9j/4AAQSkZJRgA…

Valid URI: PHOTO;VALUE=URI:https://example.com/avatar.jpg

Common mistakes:

Embedding PNG but declaring JPEG

Breaking Base64 across lines incorrectly

Using huge inline images (iOS sometimes fails silently)

Using invalid MIME parameter names

Symptoms:

No photo appears

vCard fails to import

iCloud rejects the file as invalid

How to fix:

Validate MIME type

Use Base64 only if necessary

Use external URLs for large images

11. Outlook-Specific Compatibility Issues

Outlook is famously picky.

Common Outlook errors:

Rejects vCard 4.0

Strips custom fields

Converts UTF-8 incorrectly

Ignores some TYPE parameters

Requires N: to be populated

Fixes:

Export vCard 3.0

Always include N and FN

Avoid unusual custom properties

Escape non-ASCII characters rigorously

12. Google Contacts-Specific Issues

Google is more forgiving but still has quirks.

Common errors:

Missing FN leads to outright import failures

Dates in wrong format silently dropped

ADR formatting issues ignored

Empty properties cause failure for multi-contact files

Embedded images sometimes rejected

Fixes:

Preserve 7-address-slot structure

Avoid empty fields

Validate encoding

Keep the file under a few megabytes

13. iOS/macOS Quirks

Apple has stable but strict rules.

Common iOS/macOS errors:

Rejects files missing VERSION

Misreads line folding

Converts CRLF inconsistently

Drops fields with incorrect escaping

Dislikes large Base64 photos

Fixes:

Use VERSION:3.0

Escape newline as \n

Use LF or CRLF consistently

Keep embedded photos small

14. Hidden Characters, Zero-Width Spaces, and Copy/Paste Corruption

Developers often build vCards from templates or copy/paste fields from HTML or documents.

This introduces:

Zero-width spaces

Non-breaking spaces

Smart punctuation

Invisible Unicode characters

Characters outside UTF-8

Symptoms:

Gmail gives “Couldn’t import”

Outlook cuts off fields

iOS imports but mutates characters

Fixes:

Normalize unicode before output

Strip invalid characters

Validate via a parser

15. Not Including a UID Across Contact Updates

If your users re-import contacts:

Google creates duplicates

iOS creates duplicates

CRMs create duplicates

Fix: UID:a-unique-identifier-here

This alone solves half of the “duplicate contact” problems users report.

16. Incorrect MIME Type When Downloading

Developers sometimes serve .vcf with the wrong MIME type:

application/octet-stream

text/plain

application/text

Correct MIME types:

text/vcard

text/x-vcard

Symptoms:

File downloads as .txt

Users can’t open it on mobile

Importers reject it

Fix:

Update server headers accordingly.

Final Thoughts: Validate Early, Validate Often

vCard is simple in theory, but real-world interoperability requires meticulous attention to detail. Each platform — Google, Apple, Microsoft, and the major CRMs — enforces slightly different interpretations of the spec.

The best practice for avoiding all of the above:

Validate every export in development

Validate every update in CI

Validate every user-uploaded .vcf file

CorrectVCF exists for this exact purpose: to show where the file breaks, why, and how to fix it — automatically.