CorrectVCF

✅ My .vcf File Won’t Import — Quick Checklist for Developers

A fast, practical list for engineers exporting vCard files from their application.

If your .vcf file isn’t importing into Google Contacts, iOS, Outlook, Android, or your CRM, walk through this checklist first. These are the most common reasons vCard imports fail.

1. The file has the correct extension and MIME type

  • The file must end in .vcf.
  • When serving the file, use one of these MIME types:
    • text/vcard
    • text/x-vcard
  • Incorrect MIME types (e.g., application/octet-stream) can cause downloads to break on some devices.

2. The vCard has a valid start and end

Every vCard must wrap its content between these two lines:

BEGIN:VCARD
...
END:VCARD

If either is missing, many clients won’t import the file.

3. You declared a supported vCard version

Include exactly one version line:

VERSION:3.0

or

VERSION:4.0

Common failure modes:

  • Missing VERSION entirely
  • Using deprecated 2.1 without proper encoding rules
  • Including multiple conflicting version lines

4. The vCard includes at least one name field

Most clients require a minimum identity:

FN:Jane Doe

Optionally, include the structured name:

N:Doe;Jane;;;

Empty FN: or missing both fields will often cause import errors.

5. Lines are properly encoded and escaped

vCard is strict about special characters:

  • Commas inside fields must be escaped: \,
  • Semicolons must be escaped: \;
  • Line breaks inside fields must be written as \n
  • Long lines should follow spec-compliant folding if you generate them (though most modern clients tolerate long lines)

If the text contains characters outside ASCII, make sure the file encoding is UTF-8.

6. Fields follow the correct syntax

Examples of well-formed properties:

TEL;TYPE=cell:+1-555-123-4567
EMAIL;TYPE=work:[email protected]
ADR;TYPE=home:;;123 Main St;Austin;TX;78701;USA

Avoid:

  • Missing colons
  • Using commas instead of semicolons in ADR
  • Omitting required components
  • Non-standard parameter names

7. Include a UID if your app supports syncing

Not required, but strongly recommended:

UID:123e4567-e89b-12d3-a456-426614174000

Without a UID, re-imports may create duplicates rather than updating existing contacts.

8. Multi-contact exports need correct boundaries

If your export contains multiple contacts, each must be fully wrapped:

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

Never merge two contacts inside one BEGIN/END block.

9. Test import with at least two major clients

At a minimum, test with:

  • Google Contacts
  • iOS / macOS Contacts

For extra safety, also test:

  • Outlook
  • Android (native Contacts app)
  • Popular CRMs (HubSpot, Salesforce, Zoho)

Each client has slightly different tolerances — a file that works in one may fail in another.

Minimal valid example

Here’s the shortest valid vCard most clients will accept:

BEGIN:VCARD
VERSION:3.0
FN:Jane Doe
N:Doe;Jane;;;
EMAIL:[email protected]
END:VCARD

Still having trouble?

Upload your file to CorrectVCF and we’ll validate, normalize, and repair it automatically — no spec-reading required.

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