Skip to main content

​
CSV Upload Issues

Symptoms: Error message when uploading CSV fileCommon 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
Symptoms: Column names are garbled or incorrect in previewCauses:
  • 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
Symptoms: Seeing é instead of é or similar character issuesCause: 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
Symptoms: Error about missing required Webflow columnsCause: CSV was edited and system columns were deletedSolution:
  • Re-export CSV from Webflow without modifications
  • Never delete Collection ID, Item ID, or Locale ID columns

​
Field Mapping Issues

Symptoms: “Cannot convert value to [type]” errorExample: Trying to map text like “abc” to a number fieldSolutions:
  • 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)
Symptoms: “Required field [name] missing in X rows”Cause: Some CSV rows don’t have data for a required fieldSolutions:
  • Uncheck “Required” for that field
  • Fill missing values in CSV before upload
  • Accept that rows with missing data will fail to import
Symptoms: MigrateKit suggests wrong field typesCause: Column names or data patterns are ambiguousSolution: Manually adjust mappings—suggestions are just starting points, not requirements
Current limitation: Reference/relationship fields not supported in MVPWorkaround:
  • Map as string to preserve the ID or slug
  • Manually recreate relationships in Sanity Studio after import
  • See Limitations for details

​
Connection Issues

Symptoms: Connection test fails with authentication errorCauses:
  • 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
Symptoms: Can’t connect to Sanity projectCauses:
  • 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
Symptoms: Dataset doesn’t existCauses:
  • 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
Symptoms: Can connect but can’t importCause: API token has Viewer permissions instead of EditorSolution:
  • Create new token with Editor role
  • Delete old token
  • Update token in MigrateKit

​
HTML Conversion Errors

Symptoms: Formatting doesn’t match Webflow originalCommon 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
Symptoms: Paragraphs run togetherCauses:
  • Multiple <br> tags converted incorrectly
  • Empty <p> tags were stripped
Solution: Manually add paragraph breaks in Sanity Studio where needed
Symptoms: Images that were in Webflow content don’t appearCauses:
  • 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
Expected behavior: Scripts and iframes are preserved as code blocks for securityWhat 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

Symptoms: Import completes but some rows show errorsCommon 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
Symptoms: Import takes much longer than estimatedCauses:
  • 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
Symptoms: Documents import but images are missingCauses:
  • 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
Symptoms: Import fails with duplicate document ID errorCause: Trying to import same data twiceSolution:
  • Delete existing drafts in Sanity first
  • OR MigrateKit will update existing documents (using Item ID)

​
Data Quality Issues

Symptoms: Dates appear incorrect in SanityCauses:
  • 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
Symptoms: Boolean field shows text instead of checkboxCause: Field mapped as string instead of booleanSolutions:
  • Re-map field as boolean type
  • MigrateKit converts “true”/“false”/“yes”/“no” automatically
Symptoms: 100.50 became 100.5 or similarCause: Number precision issueSolution: 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