Troubleshooting Common Issues

Solutions to common problems when migrating Webflow content to Sanity with MigrateKit.

CSV Upload Issues

CSV upload failed

Symptoms: Error message when uploading CSV file

Common causes:

• File is not a valid CSV (e.g., XLSX, TXT with wrong extension)
• File is corrupted or has encoding issues
• File is too large (>10MB)

Solutions:

• Verify file extension is .csv
• Re-export from Webflow
• Open in text editor to check for corruption
• Split large CSVs into smaller batches

CSV headers look wrong

Symptoms: Column names are garbled or incorrect in preview

Causes:

• CSV opened and saved in Excel (changed encoding)
• File has BOM (Byte Order Mark)
• Wrong delimiter (tab instead of comma)

Solutions:

• Re-export fresh CSV from Webflow
• Use Google Sheets or LibreOffice instead of Excel
• Check file encoding is UTF-8

Special characters appear corrupted

Symptoms: Seeing é instead of é or similar character issues

Cause: Encoding mismatch (file isn’t UTF-8)

Solutions:

• Re-export from Webflow (should be UTF-8)
• Convert file to UTF-8 in text editor
• Check Webflow source data isn’t already corrupted

'Collection ID' or 'Item ID' missing

Symptoms: Error about missing required Webflow columns

Cause: CSV was edited and system columns were deleted

Solution:

• Re-export CSV from Webflow without modifications
• Never delete Collection ID, Item ID, or Locale ID columns

Field Mapping Issues

Field type mismatch error

Symptoms: “Cannot convert value to [type]” error

Example: Trying to map text like “abc” to a number field

Solutions:

• Choose correct field type for your data
• Clean invalid data in CSV before upload
• Use string type if data is mixed (then convert in Sanity later)

Required field has empty values

Symptoms: “Required field [name] missing in X rows”

Cause: Some CSV rows don’t have data for a required field

Solutions:

• Uncheck “Required” for that field
• Fill missing values in CSV before upload
• Accept that rows with missing data will fail to import

Auto-mapping suggestions are wrong

Symptoms: MigrateKit suggests wrong field types

Cause: Column names or data patterns are ambiguous

Solution: Manually adjust mappings—suggestions are just starting points, not requirements

Can't map reference fields

Current limitation: Reference/relationship fields not supported in MVP

Workaround:

• Map as string to preserve the ID or slug
• Manually recreate relationships in Sanity Studio after import
• See Limitations for details

Connection Issues

'Invalid API token' error

Symptoms: Connection test fails with authentication error

Causes:

• Token was copied with extra spaces or characters
• Token doesn’t have Editor permissions
• Token was revoked or deleted

Solutions:

• Create new token with Editor permissions
• Copy token carefully without spaces
• Verify in Sanity management console that token exists

'Project not found' error

Symptoms: Can’t connect to Sanity project

Causes:

• Project ID is incorrect
• Typo in Project ID
• Using project name instead of ID

Solutions:

• Double-check Project ID in Sanity dashboard
• Copy-paste ID instead of typing
• Project ID is alphanumeric (e.g., abc123xyz), not the project name

'Dataset not found' error

Symptoms: Dataset doesn’t exist

Causes:

• Dataset name misspelled
• Dataset doesn’t exist in this project
• Wrong capitalization

Solutions:

• Verify dataset name in Sanity project settings (case-sensitive)
• Create dataset in Sanity if it doesn’t exist
• Common names: production, development, staging

'Insufficient permissions' error

Symptoms: Can connect but can’t import

Cause: API token has Viewer permissions instead of Editor

Solution:

• Create new token with Editor role
• Delete old token
• Update token in MigrateKit

HTML Conversion Errors

Portable Text looks wrong

Symptoms: Formatting doesn’t match Webflow original

Common causes:

• Complex HTML structures MigrateKit couldn’t convert
• Nested formatting beyond Portable Text capabilities
• Custom Webflow elements

Solutions:

• Review in Sanity Studio and manually fix formatting
• Simplify complex HTML in Webflow before export
• Check HTML Conversion for supported tags

Line breaks disappeared

Symptoms: Paragraphs run together

Causes:

• Multiple <br> tags converted incorrectly
• Empty <p> tags were stripped

Solution: Manually add paragraph breaks in Sanity Studio where needed

Images missing from rich text

Symptoms: Images that were in Webflow content don’t appear

Causes:

• Image URLs in HTML were invalid
• Images failed to download
• Asset upload quota exceeded

Solutions:

• Check import report for asset failures
• Verify original URLs in CSV are complete
• Manually upload missing images in Sanity

Webflow embeds became code blocks

Expected behavior: Scripts and iframes are preserved as code blocks for security

What to do:

• Review code blocks in Sanity Studio
• Replace with Sanity-compatible alternatives:
  • YouTube embeds → Sanity YouTube plugin
  • Custom scripts → Sanity-safe implementations
• See HTML Conversion

Import Errors

Some documents failed to import

Symptoms: Import completes but some rows show errors

Common causes:

• Required fields with missing values
• Data type validation failures
• Invalid Portable Text from malformed HTML

Solutions:

• Review error messages for specific rows
• Fix issues in CSV
• Re-upload and import just the failed rows

Import is very slow

Symptoms: Import takes much longer than estimated

Causes:

• Large number of high-resolution images
• Many documents (>500)
• Complex Portable Text requiring heavy processing

Solutions:

• Be patient—large imports take time
• Split into smaller batches
• Optimize/resize images before import

Assets failed to upload

Symptoms: Documents import but images are missing

Causes:

• Invalid image URLs in CSV
• Network timeouts
• Sanity asset quota exceeded
• Images too large

Solutions:

• Check import report for specific failures
• Verify URLs are accessible
• Check Sanity asset quota limits
• Manually upload failed assets

'Duplicate ID' error

Symptoms: Import fails with duplicate document ID error

Cause: Trying to import same data twice

Solution:

• Delete existing drafts in Sanity first
• OR MigrateKit will update existing documents (using Item ID)

Data Quality Issues

Dates are wrong

Symptoms: Dates appear incorrect in Sanity

Causes:

• Excel auto-formatted dates in CSV
• Timezone conversion issues
• Invalid date format

Solutions:

• Don’t open CSV in Excel (use Google Sheets)
• Verify dates in text editor before upload
• Check original Webflow data for accuracy

Links are broken

Symptoms: Links don’t work or point to wrong URLs

Causes:

• Relative Webflow URLs don’t work in new context
• Links to Webflow-specific pages

Solutions:

• Update links in Sanity Studio to absolute URLs
• Review all links after migration
• Convert Webflow internal links to new site structure

Boolean fields show 'true'/'false' text

Symptoms: Boolean field shows text instead of checkbox

Cause: Field mapped as string instead of boolean

Solutions:

• Re-map field as boolean type
• MigrateKit converts “true”/“false”/“yes”/“no” automatically

Numbers have wrong decimals

Symptoms: 100.50 became 100.5 or similar

Cause: Number precision issue

Solution: This is expected—trailing zeros are mathematically irrelevant. If you need to preserve exact formatting (like prices), use string type and format in your frontend.

Need More Help?

If your issue isn’t listed here:

Check Prerequisites

Ensure you have everything set up correctly

Review Migration Guide

Step-by-step instructions for the entire process

Limitations Reference

Current features and known limitations

Contact Support

Email [e-mail]