> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contentwrap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Common Issues

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

## CSV Upload Issues

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="'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
  </Accordion>
</AccordionGroup>

## Field Mapping Issues

<AccordionGroup>
  <Accordion title="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)
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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](/reference/limitations) for details
  </Accordion>
</AccordionGroup>

## Connection Issues

<AccordionGroup>
  <Accordion title="'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
  </Accordion>

  <Accordion title="'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
  </Accordion>

  <Accordion title="'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`
  </Accordion>

  <Accordion title="'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
  </Accordion>
</AccordionGroup>

## HTML Conversion Errors

<AccordionGroup>
  <Accordion title="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](/concepts/html-conversion) for supported tags
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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](/concepts/html-conversion#unsupported-content)
  </Accordion>
</AccordionGroup>

## Import Errors

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="'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`)
  </Accordion>
</AccordionGroup>

## Data Quality Issues

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Need More Help?

If your issue isn't listed here:

<CardGroup cols={2}>
  <Card title="Check Prerequisites" icon="list-check" href="/prerequisites">
    Ensure you have everything set up correctly
  </Card>

  <Card title="Review Migration Guide" icon="map" href="/migration/overview">
    Step-by-step instructions for the entire process
  </Card>

  <Card title="Limitations Reference" icon="info-circle" href="/reference/limitations">
    Current features and known limitations
  </Card>

  <Card title="Contact Support" icon="envelope" href="mailto:support@contentwrap.io">
    Email [support@contentwrap.io](mailto:support@contentwrap.io)
  </Card>
</CardGroup>