Migrating Media Libraries to Content Hub: Kentico Xperience Migration Guide

If you're managing a Kentico Xperience site, you've probably heard the news. Media Libraries are being sunset, and Content Hub is taking over.

The shift from Media Libraries to Content Hub represents more than just a feature update. It's a complete reimagining of how Kentico handles digital assets. The old Media Libraries system served us well, but it wasn't built for the modern, content-first world we live in today.

Here's what you need to know about the Kentico 2026 media library deadline: For Kentico Xperience, the deadline to migrate from older Media Libraries to the modern Content Hub (using Content Item Assets) is around July 24, 2026, when support fully ends, so starting now is crucial for a smooth transition to this new, recommended system.

Why Content Item Assets are the future comes down to three things: flexibility, reusability, and scalability. 

Unlike Media Libraries, which treated files as isolated entities, Content Item Assets integrate directly into your content model. This means your images, videos, and documents become first-class citizens in your CMS, with all the benefits that brings.

Think of it this way: Media Libraries were like having a separate filing cabinet for your documents. Content Hub is like having everything in one intelligent system where assets can be tagged, versioned, and reused across multiple channels without duplication.

The clock is ticking, so let's dive into how to make this Media Libraries to Content Hub migration smooth and painless.

Understanding Content Hub vs. Media Libraries

You might be wondering what makes Content Hub so different.

Let us break it down for you.

What's different about Content Hub architecture starts at the foundation. Media Libraries store files in a folder-based structure, much like Windows Explorer. You'd organize things into directories, set permissions per folder, and call it a day.

Content Hub flips this model completely, demonstrating the differences highlighted in Kontent vs Xperience when evaluating content-first architectures.

Instead of folders, you work with content items. Each asset becomes a structured piece of content with its own metadata and lifecycle. It's stored in your database alongside your other content, making it searchable, versionable, and infinitely more powerful.

The benefits of centralized asset management become obvious once you start using it. 

When an image is stored as a Content Item Asset, you can:

• Reference it across multiple pages without duplication

• Update it once and see changes everywhere

• Track its usage and relationships

• Apply workflow and governance rules

• Version it like any other content

No more hunting through folder structures to find that one product image you need. No more duplicate files eating up storage because different teams saved their own copies.

Everything lives in one place, with one source of truth.

How Content Item Assets improve scalability matters more as your site grows. With Media Libraries, adding thousands of files could slow down your file system and complicate backups. 

With Content Hub, your assets scale with your database, and databases are designed to handle massive amounts of structured data efficiently.

Plus, you get proper content modeling. Want to add custom fields to track licensing information, expiration dates, or usage rights? Easy. Try doing that with a folder full of JPEGs.

The Content Hub vs Media Libraries comparison isn't even close when you look at modern requirements. Content Hub wins on every metric that matters: performance, flexibility, governance, and integration capabilities.

This is why understanding the shift is crucial before you start your migration. You're not just moving files from Point A to Point B; you're upgrading to a completely different paradigm.

Pre-Migration Checklist: What You Need Before Starting

Before you touch anything, let's make sure you're prepared.

Trust us, the time you spend planning now will save you days of headaches later. So, let’s get to know it all: 

1. System Requirements and Version Compatibility

First things first: check your Kentico version, especially if you plan to Upgrade From Kentico Xperience 13 to Xperience by Kentico, to ensure full compatibility with the migration tools.

Most organizations running the transition need to be on at least version 29.0.0 or higher to access the full migration toolkit.

Run a quick audit of your current setup. Document which version you're running, what customizations you've made, and any third-party integrations that touch your Media Libraries.

2. Creating Database Backups for Safety

This should be obvious, but we'll say it anyway: back up everything.

Create a full database backup before you start. Not just a regular backup, a dedicated snapshot specifically for this migration. Store it somewhere safe, separate from your regular backup routine.

Test your backup by restoring it to a development environment. You want to know it works before you need it, not during a crisis at 2 AM.

Also, back up your file system where your media files currently live. Yes, the migration tool handles copying files, but redundancy is your friend here.

3. Inventory Audit: Cataloging your Media Libraries

Now comes the detective work.

You need to know exactly what you're migrating. 

Create a spreadsheet documenting:

• How many Media Libraries do you have

• How many files are in each library

• Total file sizes and types

• Custom fields and metadata structures

• Permission schemes and who has access to what

• Any custom code that references these libraries

This inventory becomes your migration roadmap. It helps you estimate how long the process will take and identify potential problem areas before they become actual problems.

We've seen migrations go sideways because someone discovered a critical library with 50,000 files only after starting the process. Don't be that person.

4. Planning Workspace Organization

Content Hub uses workspaces to organize your content. You need to decide how your migrated assets will be structured.

Will you create one workspace per old Media Library? Will you consolidate everything? Will you organize by content type or business function?

There's no universal right answer, but you need an answer before you start. Changing your mind halfway through a migration is painful.

Sketch out your target workspace structure. Get buy-in from stakeholders. Make sure it aligns with how your team actually works, not just how you think they should work.

Remember: the Kentico migration tool is powerful, but it's not psychic. It needs you to tell it where things should go.

The Technical Migration Process: Files and References

Alright, planning is done. Let's migrate some files and update your references.

This is where your step-by-step Kentico Content Hub migration actually begins.

Get to know it all below:

Step 1. Migrate Media Libraries to Content Hub

The first and most crucial step is to migrate media libraries to content hub, because this establishes the modern foundation for all your assets going forward. 

Traditional media libraries store files in a folder-centric structure, while Content Hub treats each file as a manageable, versioned, searchable asset. This shift improves scalability, metadata handling, and headless readiness. 

During the media libraries to content hub migration process, teams validate folder structures, handle duplicate assets, and ensure metadata is mapped correctly. 

The goal is not just to move files, but to elevate them into a smarter, future-proof system. Once this is complete, everything that previously depended on file system paths now becomes aligned with a structured digital asset ecosystem.

Step 2. Create a Database Backup

Once your assets have been migrated, creating a full database backup is the next essential safeguard. This snapshot preserves page references, content types, metadata fields, and system configuration exactly as they exist before deeper modifications begin. 

Because future steps involve updating asset references and potentially altering thousands of content relationships, having a solid backup ensures you can restore your environment instantly if anything goes wrong.

This step is not about caution alone, it is about protecting editorial work, preventing data loss, and ensuring a stable recovery point. A clean, verified backup acts as your safety net for the rest of the migration.

Step 3. Set Up Your Development Environment

Next, you configure a dedicated development environment to execute all migration updates without affecting production. 

This environment mirrors your live setup but gives developers freedom to adjust configurations, validate paths, test asset loading, and preview content changes. 

The development environment also enables testing automated scripts, adjusting URL rewriting, and ensuring that hybrid assets behave as expected. It essentially serves as your sandbox for validating the new asset model. 

Teams also use this phase to identify missing dependencies, test new Content Hub APIs, and ensure the project builds cleanly after the structural changes done during the media libraries to content hub migration process.

Step 4. Migrate Fields Referencing Media Library Files

Once everything is stable in development, the next step is updating content fields that previously referenced media library files. 

This is where the bulk of transformation happens. Page types, widgets, content items, and custom modules usually contain fields that point to images or documents stored in the old media library system. 

These references need to be replaced with their new Content Hub asset equivalents. Automated scripts, Kentico’s migration utilities, or custom code are used to rewrite GUIDs, file paths, or URL references. After updating, each component is tested to ensure images render correctly on the front end. 

This step ensures that no content item breaks, no layout loses visuals, and no page ends up with missing assets.

Step 5. Migrate Codebase

With field references updated, it’s time to adjust the codebase. Developers replace old APIs, update custom modules, and refactor components that previously depended on Media Libraries. 

For example, direct file system calls are replaced with Content Hub API calls. This step also involves optimizing caching, updating URL generation logic, and ensuring integration points reflect the new asset storage model. Any custom uploader or media selector inside Kentico also requires updates. 

The codebase migration is not just about compatibility — it is about ensuring the new asset system performs efficiently and aligns with modern, cloud-ready architectures.

Step 6. Deploy to Your Target Environment

Once development and QA sign off on the changes, you deploy everything into your target environment– usually production. 

This deployment contains updated asset references, code changes, and new configurations that point the system to Content Hub instead of the legacy libraries. 

At this stage, you verify the entire application: content rendering, image performance, URL rewriting, CDN behavior, and editor accessibility. 

Deployment also includes synchronizing digital assets, ensuring that all new references work in the live environment, and confirming that cached components reflect the updated media structures. This is where all prior steps come together into a functioning, stable solution.

Step 7. Delete Media Libraries

After verifying that everything runs smoothly in production, the final step is to delete old media libraries. 

This ensures no editor accidentally uploads files to the outdated system and removes redundant storage. 

Deleting old folders reduces storage costs, cleans up clutter, and eliminates the risk of outdated files being referenced. 

By removing these libraries, you enforce a singular, modern asset workflow where Content Hub becomes the authoritative source of media. This step is about tidiness, reliability, and ensuring full adoption of the new asset ecosystem.

With the Migration process being in place, it's time to talk about post-migration best practices.

Post-Migration Best Practices to Migrate Media Libraries 

Your files are migrated, your code is updated, and everything seems to work.

But you're not quite finished yet. Here are some best practices to migrate media libraries: 

1] Verifying URL Redirects and Legacy Paths

Users and search engines have bookmarked your old Media Library URLs. You need to ensure those still work.

Implement 301 redirects from old Media Library paths to new Content Item Asset URLs. This preserves SEO value and prevents broken bookmarks.

In IIS or your web server configuration, add rewrite rules like:

/sitename/media/LibraryName/* → /getmedia/{guid}/{filename}

The exact pattern depends on your URL configuration, but the principle remains: old URLs should redirect, not 404.

Test these redirects manually. Click through old links and verify they land on the correct assets.

2] Permission Mapping from Media Libraries to Content Hub

Media Libraries have been around for years and served their purpose well, but modern projects now benefit more from the structured model used in Xperience by Kentico.

You need to map your old permissions to the new system. Who had access to which libraries? How does that translate to workspace access?

This is more business process than a technical challenge. Sit down with your content team and document who needs access to what. Then configure workspace permissions accordingly.

Don't just give everyone access to everything. That defeats the purpose of having a permission system.

3] Performance Optimization for Asset Delivery

Content Item Assets can be served through CDNs more effectively than Media Library files.

Configure your CDN to cache asset URLs. Set appropriate cache headers. Enable compression for text-based assets.

Monitor your asset delivery performance. Are images loading quickly? Are there any bottlenecks?

The Kentico content asset management system is designed for performance, but you need to configure it correctly to see the benefits.

4] Cleaning up Old Media Library References

Once you've verified everything works, it's time to clean house, as recommended during any Kentico Website Migration, to prevent leftover files or broken references.

Delete old Media Library folders from your file system. They're no longer being used, and they're just taking up space.

Remove the old Media Library definitions from your site if they're not being used for anything else.

Update your documentation to reflect the new Content Hub structure. Future developers shouldn't waste time learning about a system they no longer use.

Archive any migration scripts or tools you used. You probably won't need them again, but it's good to have them documented just in case.

This cleanup phase ensures your Media Libraries to Content Hub migration leaves you with a clean, maintainable system going forward.

Real-World Migration Case Study

Recently, we worked with a client’s application that relied heavily on legacy Media Libraries, which are now sunset in Xperience by Kentico. 

To future-proof the platform, we executed a complete migration to Content Hub using Kentico’s built-in Media Library Migration Tool. All folder structures, metadata, GUIDs, and permissions were preserved flawlessly. 

We updated field definitions, replaced obsolete APIs, and refactored code to adopt Content Item Assets. After validating content integrity and deploying changes, the system transitioned smoothly with no downtime or broken links. The result: a modern, scalable, and fully compliant asset management setup ready for Kentico’s future architecture.

Future-Proofing Your Kentico Implementation

You've completed your migration. Now let's make sure you stay ahead of the curve.

The move to Content Hub isn't just about compliance with the Kentico media library sunset. It's about positioning your site for future capabilities.

1. Leveraging Reusable Content Architecture

Content Item Assets unlock true content reuse. That product image? Use it on the product page, in related articles, in email campaigns, and in mobile apps—all from one source.

Build your content types to take advantage of this. Create asset libraries organized by purpose: product images, marketing banners, documentation files, etc.

Reference assets by relationship rather than embedding them. This makes updates propagate automatically across all usage points.

The Xperience by Kentico asset management strategy is built around this reusability principle. Embrace it, and your content management gets exponentially easier.

2. Integrating with Modern Digital Asset Workflows

Content Hub integrates with external DAM systems through standard APIs. If you're using tools like Bynder, Widen, or Adobe Experience Manager Assets, you can connect them.

This means designers can work in their preferred tools while Kentico automatically pulls in approved assets. No more manual uploads and downloads.

Set up webhooks to trigger content updates when assets change in your DAM. Build workflows that automatically request approvals for new assets before they go live.

Modern digital experience platforms need this kind of integration. Content Hub makes it possible.

3. Content Hub Governance and Best Practices

Establish governance rules now, while your Content Hub is fresh:

• Naming conventions for assets

• Tagging standards for categorization

• Approval workflows for sensitive content

• Expiration policies for time-sensitive assets

• Storage quotas per workspace

Document these rules and train your team. The flexibility of Content Hub means it's easy to create chaos if everyone does things differently.

Create content templates that enforce your standards. Make the right way the easy way.

The Kentico Content Hub migration guide got you here, but governance keeps you here successfully.

Troubleshooting Common Migration Issues

Even with perfect planning, things go wrong. Here's how to fix them.

Challenge 1: Handling failed migrations

Symptoms: Migration tool reports errors for specific files or libraries.

Diagnosis: Check the Kentico event log for detailed error messages. Common causes include:

• Files locked by other processes

• Corrupted file data

• Invalid characters in filenames

• Missing source files

Solution:

• Unlock files and retry

• Fix or exclude corrupted files

• Rename files with invalid characters

• Verify source files exist before migration

Don't skip failed migrations. Investigate each one and resolve it properly.

Challenge 2: Resolving permission conflicts

Symptoms: Content editors can't access migrated assets even though they had access to the original Media Library.

Diagnosis: Workspace permissions haven't been configured to match old library permissions.

Solution:

• Map old library permissions to new workspace roles

• Create custom permission sets if needed

• Test with actual user accounts, not just admin accounts

• Document the new permission structure for your team

Permissions are often overlooked but critical for user adoption.

Challenge 3: Dealing with custom field transformations

Symptoms: Custom fields from Media Libraries don't appear in migrated Content Item Assets, or appear incorrectly.

Diagnosis: The migration tool couldn't automatically map your custom field types.

Solution:

• Manually create matching fields in your Content Item Asset type

• Use the Kentico API to migrate field data with custom scripts

• Transform data if field types don't match exactly

• Validate data integrity after manual migration

This is where your pre-migration inventory really pays off. You documented those custom fields, right?

Challenge 4: Event log monitoring tips

Symptoms: Things seem wrong, but you're not sure what.

Solution: The Kentico event log is your friend.

Set up filtered views for:

• Migration-related events (filter by "migration" keyword)

• Media-related errors (filter by "media" or "asset")

• Permission errors (often indicate access issues)

Review the event log daily during migration. Patterns emerge quickly. Ten errors in the same file? That file has a specific problem worth investigating.

Export event logs for documentation. Future you (or your successor) will appreciate having a record of what happened and how it was resolved.

These troubleshooting approaches are part of media library migration steps that separate successful projects from problematic ones.

Why Choose a Specialized Kentico Development Company for Your Migration

Look, the Media Libraries to Content Hub migration can feel overwhelming. You're juggling timelines, worried about downtime, and trying to keep your team productive while managing a major technical change.

That's where partnering with an experienced Kentico development company like DotStark makes all the difference.

We've handled dozens of Kentico migrations, from small sites with a few thousand assets to enterprise platforms with millions of files. We know the pitfalls, the shortcuts, and the exact sequence that prevents chaos.

Our team doesn't just migrate your files—we optimize your content architecture, train your team, and ensure you're positioned to leverage Content Hub's full capabilities. We work alongside your developers, not instead of them, transferring knowledge so you're self-sufficient after launch.

The July 2026 deadline is closer than you think. Let's talk about your specific situation and build a migration plan that fits your timeline and budget. Your Kentico Xperience migration doesn't have to be stressful when you have the right partner.

Ready to start? Let's make this transition smooth.

Conclusion: Embracing the Content-First Architecture

The shift from Media Libraries to Content Hub migration isn’t just a technical requirement; it’s a strategic upgrade that prepares your digital experience for the future. 

By adopting Content Item Assets, you gain a unified, flexible, and scalable content structure built for modern multi-channel delivery. 

Your assets become smarter, easier to govern, and far more reusable across your website, marketing workflows, and integrations. 

With the 2026 deadline approaching, now is the perfect time to modernize your content architecture. 

Start planning early, follow best practices, and ensure your Kentico Xperience implementation is ready for what’s next.