Sanity CLI import fails with relative file paths for assets

You're definitely not alone with this issue! This is a known behavior with the Sanity CLI's dataset import command when handling asset file paths. Here's what's happening and how to work around it:

The Problem

When you export a dataset using sanity dataset export, the resulting archive contains asset references with relative paths like file://./images/<image-name>.<ext>. However, when importing, the CLI sometimes fails to resolve these relative paths correctly, leading to the "File does not exist at the specified endpoint" error you're seeing.

According to the official Sanity documentation on this error, local file paths must be absolute, not relative.

Solutions

1. Use Absolute Paths (Your Current Workaround)

As you've discovered, using absolute paths is currently the most reliable solution. The documentation confirms this:

Correct: image@file:///Users/username/path/to/sanity/project/export/images/image-name.ext
Wrong: image@file://./images/image-name.ext

While it's frustrating to manually convert paths, this is the approach that consistently works.

2. Import the Tarball Instead of NDJSON

The importing data documentation specifically mentions this issue:

If you're getting an import error like Error: Error while fetching asset from "file://./images/<image-name>.<ext>": File does not exist at the specified endpoint, you can either (1) make the filenames absolute or (2) import a tarball (including assets) rather than an ndjson file.

So instead of extracting and importing just the .ndjson file, try importing the compressed tarball directly:

sanity dataset import production.tar.gz your-dataset

This keeps the assets bundled with the document data and should handle paths more reliably.

3. Run Import from the Export Directory

Make sure you're running the sanity dataset import command from the same directory where the export files are located. The relative paths are resolved relative to your current working directory.

4. Use the --allow-failing-assets Flag

If some missing assets are acceptable for your use case, you can use:

sanity dataset import your-export.tar.gz your-dataset --allow-failing-assets

This allows the import to continue even when some assets can't be found.

5. Automate Path Conversion

If you're doing frequent exports/imports, consider writing a script to automatically convert relative paths to absolute ones in your export files. You could extract the tarball, modify the .ndjson file with a find-and-replace script, and re-import.

Why This Happens

The CLI's handling of relative file paths in asset references has been inconsistent across different operating systems and execution contexts. The path resolution logic doesn't always correctly interpret ./ relative to the archive location or the current working directory.

Bottom Line

This is a known limitation of the import tool, not something you're doing wrong. Your workaround of using absolute paths is actually the officially recommended approach. For the most reliable imports, stick with importing the full tarball rather than extracted NDJSON files, or use absolute paths when you need more control.