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.
The migration tool GitHub repository (opens in a new tab) 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 (opens in a new tab) before submitting your issue.
Our Learn portal (docs.kentico.com) (opens in a new tab) 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 for developers.
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 (opens in a new tab) 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 (opens in a new tab).
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 (opens in a new tab) 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 (opens in a new tab) to skip the automatic checks.
You can exclude an entire site by configuring (opens in a new tab) the Settings.EntityConfigurations.CMS_Site.ExcludeCodeNames option in the Migration.Tool.CLI/appsettings.json file.
This prevents the migration tool from creating a website channel for each of the specified sites and stops pages, page attachments, customers, and orders associated with those sites from migrating. Currently, there is no configuration-based way to exclude other objects associated with the sites, such as forms, roles, users, media files, and activities. You may need to handle them post-migration, for example, by creating a script or manually deleting unwanted objects.
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 (opens in a new tab).
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 (opens in a new tab) for details.
If migrated content types contain fields with names used internally in Xperience by Kentico (Asset or SystemFields), rename those fields after migration. For naming rules, see Field naming guidelines.
If your solution uses any of the unsupported field types heavily, we recommend auditing your content model early and budgeting additional time for rebuilding these fields using alternative approaches in XbyK.
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.
Yes and we encourage auditing and re-evaluating your content model.
The migration tool allows you to optimize your content model, converting pages into reusable content items, or using objects newly introduced in XbyK, 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 all available customization options to remodel data (opens in a new tab) during migration.
For concrete scenarios and hands-on learning, check out our technical deep dives.
Some field data types, such as GUID or Time interval, are not supported out of the box by the Kentico Migration Tool (opens in a new tab) because Xperience by Kentico has no matching form components for them. When the tool migrates these fields, it automatically hides them in the UI to prevent validation errors.
To migrate these fields successfully, you need to set up custom class mapping (opens in a new tab) and instruct the tool how to handle the field and which form component to use. Note that your class mapping needs to explicitly set the field's visibility to true and define the form component and its settings. The tool hides unsupported fields by default, and this default behavior is not overridden automatically by your custom mapping, even when isTemplate: true is set.
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 updating all content you want to transfer into a "published" state. For content you don't want to migrate, either configure the migration tool to skip it or remove/archive it beforehand.
You can keep adding content in KX13 and run the migration again when your XbyK project is ready. The migration tool does not remove existing data in the target. However, the tool does not fully track what has been migrated in past runs, so defining the delta is your team's responsibility. For example, if you create new content in KX13 using already migrated page types and run the migration process again, the tool transfers only the new content and doesn't duplicate already migrated data.
Be careful: if you change already migrated content in the source KX13 instance, for example, remove pages from the content tree, and run the process again, these changes will not be promoted.
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 warns you if anything 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.
Yes. The migration tool operates in upsert mode, meaning it adds or updates content without deleting any existing content in the target XbyK instance. This makes it safe to run against a non-empty environment. For example, you can define new content types in XbyK to remodel your migrated project, then map them to the corresponding source objects in KX13 without affecting existing content in the destination instance.
Migrating from Kentico Xperience 13 MVC 5 (KX13) is more complex than migrating from Kentico 13 .NET Core, because it involves two transformations: upgrading your application framework from ASP.NET MVC 5 (.NET Framework) to ASP.NET Core, and upgrading the Kentico platform itself.
The MVC 5 to .NET Core upgrade alone requires rewriting core application infrastructure. You need to:
System.Web dependencies with Microsoft.AspNetCore equivalents.Global.asax to Program.cs/Startup.cs patterns.Web.config to appsettings.json.Autofac, or switch to the built-in dependency injection.Controllers need updates for new namespaces and return types.Widgets should be rebuilt from WidgetController to ViewComponent, with new file locations and caching.IPageRetriever instead of the old provider APIs.You can use Microsoft's GitHub Copilot app modernization (opens in a new tab) to analyze your solution. Then you can follow Microsoft's (opens in a new tab) and Kentico documentation (opens in a new tab) (for Kentico 12 → Kentico 13), including a Copilot-assisted migration tool that highlights the most important changes.
In contrast, migrating from Kentico 13 to .NET Core requires only the Kentico platform migration, as your codebase already uses the modern framework and architectural patterns. The Kentico Migration Tool (opens in a new tab) and the KentiCopilot codebase migration skills (opens in a new tab) are designed to work with .NET Core projects. Moreover, all of Kentico's sample code, upgrade guidance, and pre-built AI agent skills assume your KX13 project is running on .NET Core.
This is why we recommend upgrading your codebase to .NET Core before attempting the Kentico platform migration. You’ll tackle each challenge separately and can leverage existing Kentico tooling when upgrading to Xperience by Kentico.
Depending on your timeline and resources, you have several approaches available: a manual rewrite of the MVC 5 project to .NET Core following Microsoft's migration guidance, leveraging both Microsoft's Copilot-assisted tools for the framework upgrade and then the Kentico migration tool for the platform migration, or working with experienced Kentico partners who have completed similar migrations. The key is to approach this as a two-phase effort - first, perform framework modernization, then upgrade to Xperience by Kentico, rather than attempting both simultaneously.
Timelines vary based on your solution's features, customization level, project size, remodeling requirements, and team experience.
Plan adequate time for familiarizing yourself with XbyK, understanding the migration tool, and preparing for development, testing, and deployment.
We've prepared a guide to help you estimate the migration complexity based on the features your solution uses.
If your project uses e-commerce, see our commerce project timeline considerations.
Migration projects often take longer than expected due to teams underestimating the complexity of the migration process. Common reasons for slow migration include limits of the migration tool, lack of resources, and underestimating the time needed to learn how to use the migration tool for content changes and testing.
Problems often happen when partners do not spend enough time learning what the tool can do, do not check carefully which KX13 features are available in XbyK that leads to knowledge gaps and surprises, and developers are not familiar with the migration steps. Another issue is that teams often do not plan enough time to replace missing features from KX13 that are not available in XbyK.
Mitigation strategies:
We recommend performing an audit of your content model before an upgrade rather than performing a direct migration. The most critical part of a successful project is designing a content model that fits XbyK's architecture and your project goals.
We strongly recommend completing your content model planning before beginning migration. Direct migrations from KX13 often result in deep tree-based relationships that mix pages and non-navigable content which is not recommended for XbyK. Insufficient planning can lead to projects going "way over budget" due to extra code and missed optimization opportunities.
Consider XbyK's unique features when planning content model granularity, such as:
XbyK favors flat content relationships over deep tree structures. Depending on your project and requirements, consider flattening tree structures into content relationships using reusable content with linked items.
Kentico Migration Tool out-of-the-box provides ways to transfer the hierarchy into Content hub or turning child pages into content items referenced in widgets.
Planning for Content hub structure that doesn't rely on content tree hierarchy in the long run significantly improves editor experience, increases developer efficiency, and provides better performance and maintainability.
Media libraries are obsolete in XbyK and you should definitely migrate to Content hub. This provides significant advantages but requires planning for the architectural changes. See more details in our Plan your strategy for migrating features page.
Yes, if your solution uses permanent links to a media library file, the migration tool will automatically convert them into references to asset content items with the correct configuration (opens in a new tab).
Note that this conversion is only supported for permanent links.
If you are using links to media library files in a third-party system or a document, you will have to either update the links or set up redirects.
No. The migration tool reads media library files from the local file system only. If your source instance stores media files in Azure Blob Storage, Amazon S3, or other remote/cloud storage, the tool cannot read files directly from these locations.
In this case, you have two options:
~/media/ folder of your KX13 instance. You can use tools like Azure Storage Explorer (opens in a new tab) or the Azure CLI (opens in a new tab) for Azure, or equivalent tools for other cloud providers.MigrateOnlyMediaFileInfo to true – this migrates only the database records without the binary files. You then transfer the files to the target storage after the migration based on your project's storage setup.We recommend avoiding migrating pages that are currently checked out, as they may not transfer properly and could result in missing or inconsistent content. Before you begin the migration, make sure to check in all the pages you want to transfer to Xperience by Kentico. This helps ensure your content is complete, stable, and ready for a smooth migration.
No, you cannot successfully migrate attachments stored only on the file system to Xperience by Kentico.
The migration tool requires attachment data to be available in the database (specifically, the BinaryAttachment field must not be null). If attachments are missing from the database, the migration tool logs an error.
To ensure a successful migration, you need to:
This ensures the migration tool can detect and transfer all attachments correctly.
Xperience by Kentico now covers most functionality that KX13 offered. With modernization, some concepts work differently in XbyK. Additionally, XbyK includes new features not present in KX13 that can greatly benefit your project and your client's business, such as customer journeys, AI capabilities, and Content hub.
For a detailed comparison of both systems, refer to our Plan your strategy for migrating features guide.
Kentico partners can find a detailed feature comparison overview in the Partner Portal (opens in a new tab).
Plan how you will host the Administration UI and set up your deployment pipeline before the first cut-over.
In XbyK, 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.
XbyK 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.
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.
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 (opens in a new tab).
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.
No, all users (including editors and your customer users) will need to create new passwords using the invitation or password recovery flow. KX13 used ASP.NET Forms authentication with different security and hashing mechanisms than the ASP.NET Core Identity system used in XbyK.
It depends on your team's expertise and experience with Kentico project migrations and complex upgrade projects. If you're comfortable handling these internally, you may not need additional support. However, Kentico offers several resources to help ensure a smooth and successful transition:
Client communication support: Kentico Customer Success Manager can assist in explaining technical details to your clients and help you clearly communicate changes and upgrade flow throughout the process.
Engaging Kentico can give you confidence that your migration strategy is sound and reduce the risk of unexpected challenges.
Clients are often surprised by the scope and complexity of upgrading to XbyK compared to previous Kentico version upgrades. Proactive communication about XbyK's architectural differences is essential for managing expectations.
Common client questions and concerns:
Effective communication strategies:
The key is to frame the migration as an investment in future-proofing their digital presence rather than just a technical upgrade.
While clients may prefer lift-and-shift due to budget constraints, complete remodeling often provides better long-term value.
Lift-and-shift reality:
Complete remodeling benefits:
If you are working on an upgrade for a client, it is important to educate them on what they're sacrificing with the lift-and-shift approach.
We do not recommend delaying migration beyond the end-of-life date for KX13, which is scheduled for 2026. After this date, we do not plan to extend full product support, including security updates and critical fixes.
If your client has signed a quote to begin migration in 2026 but expects the project to continue past the end-of-life, we strongly encourage discussing options with the Kentico Partnership Team. They can help explore strategies to minimize risk and ensure continuity during the transition.
Why moving earlier helps your project:
For personalized guidance, please reach out to your Customer Success Manager or the Partnership Team. They can help you plan a smooth and future-proof transition.
Got questions about our commerce capabilities or wondering about moving from KX13 to XbyK? This section provides clear, concise answers on XbyK's capabilities, integration strategies, and upgrade pathways.
Yes, commerce is a core feature of XbyK and is production-ready. However, it’s important to note that the current capabilities are not identical to previous Kentico versions. Before starting your project, we recommend reviewing which features you need, to ensure they are available in XbyK out-of-the-box, and plan for custom implementation of any missing functionality.
Key points to keep in mind:
For guidance on what's currently supported and best practices for implementation, refer to the XbyK documentation and the commerce features overview.
It’s not possible to provide a universal estimate for timeline or costs, as these vary significantly based on several factors:
For accurate planning, we recommend conducting a migration audit and discussing your specific scenario with Kentico’s Consulting team or your Customer Success Manager. They can help you assess complexity and outline a realistic timeline and cost estimate.
No, there is no change to the licensing. Commerce is a core product functionality, and you can leverage it in any of your digital marketing channel within your digital marketing mix. You can purchase additional channels (opens in a new tab) if needed.
If you have any questions or need clarification, we recommend reaching out to your Customer Growth Manager—we’re happy to guide you through the details.
It is technically possible to migrate commerce widgets from previous Kentico versions. However, the level of customization required during the upgrade process depends on both the Kentico version and the customizations implemented in the Kentico source project.
Recommended approach: Instead of migrating KX13 widgets "as-is", consider remodeling and rebuilding the widgets during migration to ensure a consistent look and feel, better performance, and long-term maintainability. You can leverage AI to assist you in extending extending existing or implementing new commerce widgets.
No, support for the KX13-XbyK commerce bridge (opens in a new tab) will not be extended. The Bridge was introduced as a temporary solution to help projects transition before XbyK gained full native commerce capabilities. Its repository is archived and read-only – the source code, releases, and published NuGet packages remain available, but the repository no longer accepts issues or pull requests.
With XbyK, you can now handle all scenarios previously orchestrated by the bridge natively, using built-in commerce features.
Moving to native commerce functionality in XbyK offers several benefits:
If you have any concerns about migrating from the bridge or need guidance on implementing native commerce features, please reach out to the Kentico Customer Success Manager or Consulting teams. We’re here to help ensure a smooth transition.
No, multi-store scenarios are not supported in XbyK. XbyK is designed as a single-tenant solution, meaning customer and order entities are global across the entire application. There is currently no roadmap for introducing multistore capabilities (opens in a new tab).
What are your options?
Important distinction:
If your scenario involves store managers who must not access data from other stores, then full data isolation via separate instances is the recommended approach.
Yes, you can migrate your backend code to XbyK, but the effort depends on the type and extent of customization:
In short, backend tasks often migrate with minimal changes, while UI customizations require a full rewrite. We recommend auditing your existing customizations to estimate the effort and avoid surprises during the upgrade.
No, there is currently no dedicated product inventory application in XbyK. Instead, we recommend modeling your product catalog using the content storage options provided by Xperience.
You can store products either as reusable content items in the Content hub or as pages in a website channel, depending on your scenario. Note that Xperience does not include dedicated commerce fields (such as price, currency, or stock).
For detailed guidance, please refer to the Content modeling guide and explore commerce best practices for structuring your product catalog.
The Kentico Migration Tool (opens in a new tab) does not natively support migrating KX13 SKUs to XbyK.
To transfer product data from KX13, you might want to consider customizing the Universal Migration Tool to correctly migrate SKU data into the new content model in XbyK. Please note that the Universal Migration Tool provides a good starting point, but it may not be sufficient for all projects.
For complex scenarios, we recommend building custom functionality to handle the migration and leverage the XbyK Content Management API for precise control and automation.
XbyK is a new product, not a direct continuation of KX13. Its data structures particularly for commerce entities, such as orders or customers, differ significantly from previous versions.
In KX13, it was common for partners and clients to customize default commerce objects by adding additional fields to meet specific business needs. These customizations will not automatically carry over during migration.
To ensure your XbyK instance includes all necessary fields and maintains data integrity:
For best results, thoroughly review your current data model and plan your migration based on both the source Kentico version and the extent of customizations in that version.
Currently, we provide a sample implementation of commerce functionality in the Dancing Goat project, which developers can install locally. This example demonstrates the commerce features supported by XbyK and serves as a helpful starting point for building your own solution.
However, please note:
For guidance, refer to the Dancing Goat sample project, the official Xperience by Kentico documentation, or feel free to reach out to the Kentico Consulting team for additional support.
Yes, we recommend modeling product variants as child items of a parent product. The parent holds shared information, while each variant contains only the fields that differ (e.g., size or color). You can define dedicated content types for variants and use reusable field schemas to efficiently manage shared and variant-specific data.
For full guidance and examples, please refer to the official documentation about modeling product variants.
In XbyK, product categorization is handled differently than in previous versions. Instead of using COM_Department or COM_Collection, you can organize and categorize your product catalog using:
While the content tree can be used for organizing products, it’s only recommended for very small catalogs—not for categorization purposes.
Additionally, the Content hub offers powerful tools like workspaces, folders, and smart folders to help structure your catalog effectively.
For more details and best practices, please refer to the Kentico documentation.
By default, tax is not calculated automatically. XbyK provides a flexible interface for handling tax calculations that requires some configuration. Your developers need to implement a custom tax calculation step to apply the correct tax logic for your business. Once set up, the system will automatically apply tax during price calculations, including unit prices, subtotals, shipping, and final totals.
Refer to a sample implementation in the Dancing Goat demo project that shows how to calculate and apply taxes in real-world scenarios.
XbyK contains built-in promotions with catalog discounts (product-level price reductions), order discounts (cart-level promotions), and general gift cards that use generic codes like "DISCOUNT25OFF" available to all customers.
Additional discount capabilities are on the roadmap, including unique per-user coupons, Buy X, Get Y (opens in a new tab) promotional rules, and extensibility options that allow developers to customize the built-in discount engine for project-specific business logic.
What's currently available:
For complex pricing scenarios beyond the built-in discount engine, such as customer-segment-specific pricing, complex volume-based tier pricing, or dynamic pricing based on external factors, you can model custom pricing fields in your product content types, develop a dedicated custom module, or integrate a 3rd-party discount engine into the pricing calculation.
Yes, Kentico Migration Tool supports migrating orders and customers since January 2026.
XbyK does not include built-in support for customer credit history like KX13 did. However, you can implement this functionality through custom development.
To replicate features such as credit balance tracking, transaction history, using credit as a payment method, and refund processing, you’ll need to extend the customer profile and create a custom interface for managing credit events.
A typical credit event entry might include:
This approach allows you to tailor credit handling to your specific business rules and integrate it with other systems if needed.
Did this page address your concerns or are you missing some information? Let us know using the Send us feedback button.