CorrectVCF

Common vCard Import Errors and How to Fix Them

If you’re seeing a vCard import error like “invalid vCard” (iCloud, Google Contacts, Outlook, etc.), the fastest path is: Upload your file to CorrectVCF.

This guide covers the most common vCard import failures across iCloud, Google Contacts, and Outlook.

For the iCloud‑specific UTF‑8 BOM issue, see: Fix iCloud vCard UTF‑8 BOM Import Issue.

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 record boundaries. Missing one can 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 a large portion of 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 (breaks some importers)

Symptoms

  • Non-ASCII characters appear as �
  • Gmail rejects the file as “invalid”
  • iOS silently fails to import
  • Outlook truncates content

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: “We couldn’t import some contacts”
  • iOS creates a blank, nameless card
  • Outlook rejects the vCard entirely

How to fix

  • Include both FN and N
  • Ensure they’re not empty
  • Escape special characters correctly

4. Incorrectly formatted address fields (ADR)

The 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
  • 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 the address but breaks components incorrectly

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 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 importers vary: some accept folded lines, some reject them, and some unfold them incorrectly.

Common mistakes

  • Folding without a leading space
  • Folding mid-UTF-8 character
  • 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 (many modern systems allow long lines)
  • If necessary, follow RFC rules exactly
  • Run output through a linter/validator

8. BOM (Byte Order Mark) at start of file

Some libraries output UTF-8 with BOM:

BEGIN:VCARD

Importers may treat this as corruption.

Symptoms

  • Gmail refuses import
  • iOS shows invisible/odd 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 bytes of the file

9. Incorrect date formats (BDAY & ANNIVERSARY)

Many developers output human-readable dates:

BDAY:04/23/1985

Correct format:

BDAY:1985-04-23

Symptoms

  • Birthday not imported
  • Outlook uses the wrong year
  • Google Contacts quietly drops the date

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 the wrong format are silently dropped
  • ADR formatting issues ignored
  • Empty properties cause failure for multi-contact files
  • Embedded images sometimes rejected

Fixes

  • Preserve the 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

Building vCards from templates or copy/paste (HTML/docs) often introduces:

  • Zero-width spaces
  • Non-breaking spaces
  • Smart punctuation
  • Invisible Unicode characters
  • Characters outside UTF-8

Symptoms

  • Gmail: “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 users re-import contacts, a missing UID often creates duplicates across Google, iOS, and CRMs.

Fix:

UID:a-unique-identifier-here

This alone solves a large portion of “duplicate contact” problems.

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

How to 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 enforces slightly different interpretations of the spec.

Best practice:

  • 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.

Fix your .vcf file in seconds

Upload a vCard and get a clean, import-ready file for Google Contacts, Outlook, iPhone, Android, and CRMs.

Try the CorrectVCF Autofix Tool Back to Help