Sitecore migration not working on Windows and PowerShell

[erikpost]

The sitecore migration seems to have issues on Windows due to incorrect file separator being used. When going from step 2 (Configure Destination Stack) to Step 3 (Map Content Fields), the migration tools shows that there are no Content Types available while in fact there are.

The tool has been run on two different Windows machines, both using Windows Terminal and PowerShell 7.

The console log of the upload-api application shows the following error:

🚀 ~ createSitecoreMapper ~ err: TypeError: Cannot read properties of undefined (reading '$')
    at createTemplate (C:\repos\sandbox\migration-v2\upload-api\migration-sitecore\libs\contenttypes.js:26:19)
    at singleContentTypeCreate (C:\repos\sandbox\migration-v2\upload-api\migration-sitecore\libs\contenttypes.js:648:20)
    at C:\repos\sandbox\migration-v2\upload-api\migration-sitecore\libs\contenttypes.js:687:7
    at Array.forEach (<anonymous>)
    at ExtractContentTypes (C:\repos\sandbox\migration-v2\upload-api\migration-sitecore\libs\contenttypes.js:686:13)
    at C:\repos\sandbox\migration-v2\upload-api\build\controllers\sitecore\index.js:68:15
    at Generator.next (<anonymous>)
    at fulfilled (C:\repos\sandbox\migration-v2\upload-api\build\controllers\sitecore\index.js:5:58)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
{"level":"warn","message":"Validation error: File validation failed.","status":401,"timestamp":"2025-07-07T09:10:23.490Z"}

I have traced this back to the function ExtractContentTypes in upload-api/migration-sitecore/libs/contenttypes.js where a path split is done on line 680 where a forward slash is used instead of a backward slash.

Suggestions is to use Node's path.sep to get the correct file separator depending on the platform where the tool is run.

[umeshmore45]

Thank you for reporting the issue and for your detailed analysis.

We acknowledge the problem with path separators on Windows. We are actively working on adding full support for Windows machines and expect this to be addressed in the next release.

In the meantime, as a workaround, you can use a pre-stage branch with Docker to run the migration tool successfully on Windows. This approach avoids path separator issues by running the application in a Linux container.

We appreciate your patience and understanding while we work on this improvement.

Docker setup Document:

🐳 Docker Setup For Migration Tool

Overview

This Docker-based CMS migration tool supports migrating data from multiple CMS platforms including Sitecore, Contentful, and WordPress.

Prerequisites

• Docker and Docker Compose installed

• Bash shell (macOS/Linux) or Git Bash/WSL (Windows)

• CMS data files in supported formats

🚀 Quick Start

1. Run the Setup Script

macOS/Linux:

chmod +x setup-docker.sh && ./setup-docker.sh

Windows (Git Bash or WSL):

chmod +x setup-docker.sh && ./setup-docker.sh

2. Select CMS Type

The script will prompt you to choose from:

• Sitecore (.zip files)

• Contentful (.json files)

• WordPress (.xml files)

3. Provide Data File Path

Enter the full path to your CMS data file when prompted.

Supported File Formats

CMS Type | File Format | Example -- | -- | -- Sitecore | ZIP | sitecore.zip Contentful | JSON | contentful.json WordPress | XML | wordpress.xml

⚙️ Environment Configuration

The script automatically configures the following environment variables in ./upload-api/.env:

• CMS_TYPE: Selected CMS platform

• CMS_DATA_PATH: Path to your data file

• CONTAINER_PATH: Docker container path mapping

• NODE_BACKEND_API: Backend API endpoint

Docker Services

The tool uses Docker Compose to orchestrate the following services:

• Migration API: Backend processing service (port 5001)

• Upload API: File upload and processing service

• Database: Data storage service

🧐 Troubleshooting

Common Issues

File Not Found Error

❌ File does not exist: /path/to/file

• Verify the file path is correct.

• Check file permissions.

• Ensure the file exists in the specified location.

Permission Denied

If you encounter a permission error running the script, make it executable:

chmod +x setup-docker.sh

Docker Build Issues

If services fail to start, try a clean rebuild:

docker compose down
docker compose up --build --force-recreate

Windows Tips

• Use Git Bash or Windows Subsystem for Linux (WSL) to run shell scripts.

• Provide full paths using Unix-style format (e.g., /c/Users/yourname/data/file.zip).

• Ensure Docker Desktop is running with WSL 2 integration enabled.

Script Workflow

1. CMS Selection: Interactive menu for platform selection.

2. File Validation: Checks if the specified data file exists.

3. Environment Setup: Creates/updates the .env file with configuration.

4. Docker Deployment: Builds and starts the containerized services.

📂 File Structure

migration-v2/
├── setup-docker.sh        # Main setup script
├── docker-compose.yml     # Docker services configuration
├── upload-api/
│   ├── .env               # Environment variables
│   └── ...                # API source code
└── README.md              # This documentation

Usage Examples

Sitecore Migration

./setup-docker.sh
# Select option 1 (sitecore)
# Enter: /Users/username/data/sitecore-export.zip
# Windows: "C:\\Users\\username\\data\\sitecore-export.zip"

Contentful Migration

./setup-docker.sh
# Select option 2 (contentful)
# Enter: /Users/username/data/contentful-export.json
# Windows: "C:\\Users\\username\\data\\contentful-export.json"

WordPress Migration

./setup-docker.sh
# Select option 3 (wordpress)
# Enter: /Users/username/data/wordpress-export.xml
# Windows: "C:\\Users\\username\\data\\wordpress-export.xml"

API Endpoints

Once running, the migration API will be available at:

• Backend API: http://localhost:5001

• Upload API: http://localhost:3000 (if configured)

Support

For issues or questions, check the troubleshooting section or review the Docker logs:

docker compose logs -f