Upgrade - Frequently asked questions
This FAQ page addresses common questions about using the Kentico Migration Tool to upgrade from Kentico Xperience 13 (KX13) to Xperience by Kentico (XbyK). It covers migration scope, testing strategies, and technical challenges that solution architects and tech leaders typically encounter during the upgrade process.
What is the difference between the documentation in the GitHub repo and on the docs.kentico.com site?
GitHub repository documentation
The migration tool GitHub repository is the official tool reference and public issue tracker. It’s a public repository, where you’ll find information about CLI usage, configuration, supported objects and mapping rules, plus release notes and known limitations.
If you encounter an error or a bug during data migration, we encourage you to open an issue in the GitHub repo or look for an existing issue matching your problem before contacting our support or consulting.
Support will likely recommend going through the repo anyway, as it’s the single source of truth for tool behavior and bugs, and public issues let everyone see existing reports, workarounds, and progress.
To avoid sharing sensitive client data, you can use the community anonymizer tool before submitting your issue.
Upgrade resources on Learn portal (docs.kentico.com)
Our Learn portal (docs.kentico.com) provides end‑to‑end guidance on how to use the Kentico Migration Tool. Our materials focus on implementation scenarios, upgrade planning, environment preparation, iterative data migrations, and other specifics.
As a starting point, see Upgrade from Kentico Xperience 13. For advanced technical topics, like remodeling, check out our Upgrade deep dives for developers.
Can I run the Kentico Migration Tool against my project multiple times?
Yes, data migration is designed to be iterative. Many teams run the tool, review the outcome, adjust the configuration, and run it again. Our overview guide illustrates the high‑level flow. Keep the scope small and run in batches - see the GitHub README file for list of parameters to migrate only certain objects.
Make sure to create a database backup between data migration runs. With a backup, you can easily reset your environment and start with a clean slate. Avoid manually deleting partially migrated content, as errors during migration can prevent the admin UI from working correctly. Restoring from backup is the safest way to undo failures or incorrectly migrated data.
Be mindful of chain dependencies between migrated objects. For example, to migrate custom modules or page types, you first need to migrate sites.
The migration tool performs automatic checks of the dependencies and will alert you to issues.
You can bypass the automatic checks using the --bypass-dependency-check parameter - see details in the Migration.Tool.CLI README file in GitHub.
How can I restrict which page types to (re)migrate?
You can configure selective migration in the Migration.Tool.CLI/appsettings.json file before each migration tool run. See in our step‑by‑step walkthrough, where the configuration fits into the process.
For scope control, use the EntityConfigurations option to exclude objects by code name (block‑list). At this time, the tool does not support a native allow‑list; you can emulate it by excluding everything except the target page type(s).
For one‑type runs, temporarily exclude other page types, run the migration, review results, adjust, and repeat.
For re‑migration, restore a pre‑run database backup and run again with updated exclusions. Avoid manual partial deletes to prevent dangling references.
Be mindful of dependencies and links. Include required parents, taxonomies, media, and custom module data in the same run (or migrate in the correct order) to avoid errors during migration.
The tool will warn you about missing chain dependencies (e.g., you’re migrating page types without sites). If you are absolutely sure the dependencies have been migrated beforehand, you can use the --bypass-dependency-check parameter to skip the automatic checks.
Which data can and cannot be migrated?
You can migrate the majority of objects from KX13, including custom object types and custom classes and their data, pages, sites, contacts (and activities), and forms with submitted data. See the full list with details and limitations in the Migration.Tool.CLI README in GitHub.
Some objects have different names in XbyK (e.g., sites -> websites), and some objects map one-to-one, while others don’t, expect to review mappings and adjust.
For content types, most fields map automatically, though some limitations apply (no page type inheritance, no macros in field defaults, no field categories). See the GitHub documentation for details.
You need to manually migrate or reimplement emails (templates, emails/campaigns) and marketing email recipient lists.
For planning trade‑offs and feature differences, see our capability comparison guide.
Can I change the structure of my content during data migration?
Yes. The migration tool allows you to optimize your content model, using objects newly introduced in Xperience by Kentico, for example, Reusable field schemas (RFS).
The RFS are optional and not required to complete the migration; use them for shared or repetitive fields when remodeling.
See one of our technical deep dives on how to remodel page types using the RFS during data migration.
Are there special considerations when deploying an upgraded project to production for the first time?
Plan how you will host the Administration UI and set up your deployment pipeline before the first cut‑over.
Administration UI
In Xperience by Kentico, the administration UI is not on a separate domain by default.
If you require a different domain for the administration, a common setup is to run two application instances against the same database: one with the Admin enabled on a restricted domain for editors, and one without the Admin for the public site domain.
For more guidance, see our documentation on how to configure the administration domain correctly.
Continuous delivery
Xperience by Kentico supports Continuous deployment and Continuous Integration. Set up your CI/CD pipelines (e.g., Azure DevOps, GitHub Actions) before your first production deployment to move schema and configuration changes through code and simplify long‑term maintenance.
Security and operations
Consider how you can protect the Admin endpoint (use a separate domain if required, IP allowlisting, SSO/MFA, HTTPS), validate web‑farm configuration when running multiple instances, and test the whole pipeline in a staging environment before go‑live.
Are there special considerations when performing an upgrade using Xperience by Kentico SaaS?
In short, deploy to SaaS the same way as any other Xperience project. Follow the SaaS deployment steps. Ensure your target Xperience project was installed with the --cloud parameter so it includes cloud‑specific configuration and deployment scripts.
If your deployment package exceeds 2 GB, utilize the custom restore feature to upload your data instead.
Deploying via deployment packages in Saas currently triggers downtime–we are working toward minimizing this.
If you choose to use Content sync, note that you should carefully configure it ahead of time. For example, you must deploy your content types with a deployment package before you can sync content.
Do I have to update my KX13 site before migration?
For the migration to run correctly, your source KX13 project has to run on Refresh 5 or newer. If your source instance runs on a lower version, yes, you need to update before data migration.
We recommend to update all content you want to transfer into a “published” state and remove or archive content you don’t wish to migrate.
Can I continue adding to my KX13 site while we are attempting the migration or do we need a content freeze?
Yes. You can keep adding content in KX13 and run the migration again when your Xperience by Kentico project is ready. The Migration Tool does not remove existing data in the target; it imports new data in subsequent runs.
When you run the data migration iteratively, we highly recommend taking database backups between runs; see the Can I run the Kentico Migration Tool against my project multiple times? question.
Be mindful of dependencies when you perform additional migration runs: include or migrate required parents and related data (e.g., sites/channels, content types, taxonomies, media, custom module data) in the correct order, or in the same run. The migration tool performs dependency checks and will warn you if something is missing.
Before the final cut‑over, plan a short content freeze window (or schedule one last delta migration) to avoid losing last‑minute changes.
Did you find the answers you were looking for?
Did this page address your concerns or are you missing some information? Let us know using the Send us feedback button.