Skip to main content

Check for removed property editors and macros before upgrading from Umbraco 13 to 17

Which editors and features were removed in Umbraco 14, how to find them in a v13 project, and why to replace them before upgrading to 17.

Written by Joana Knobbe

Type: How-to
​Category: Umbraco CMS > Versions & Upgrades
​Tags: major upgrade, v13 to v17, legacy Media Picker, Nested Content, Grid Layout, macros, removed property editors, Block List, Block Grid, Umbraco Deploy, Unknown entity type macro
​

Product: Umbraco CMS, Umbraco Cloud
​Version: Upgrades from 13 (or older) to 14 and later, including 17


Umbraco 14 removed a few older property editors and macros. If your v13 project still uses any of them, the upgrade to 17 can leave behind data types, content and schema files that the new version can't work with.

The easiest time to deal with this is before you upgrade, while you're still on 13 and the old and new editors both exist side by side.

Scope: This applies to Umbraco Cloud and self-hosted projects moving from Umbraco 13 or older to 14 or later. It covers finding and replacing removed features. For the rest of the upgrade (packages, .NET, code changes), see Find Your Upgrade Path.

What was removed in Umbraco 14

Removed

Use instead

Media Picker (legacy)

Media Picker

Nested Content

Block List or Block Grid

Grid Layout

Block Grid

Macros and partial view macros

Partial views, or blocks in the Rich Text Editor

Step 1: Find what your project still uses

Do this on your v13 project, before you upgrade.

  1. Check your data types. In the backoffice, go to Settings > Data Types. Open each data type and look at the property editor it uses. Note any that use Media Picker (legacy), Nested Content or Grid Layout.

  2. See where they're used. For each data type you noted, find the document types and element types that use it. That tells you which content will need moving.

  3. Check your macros. Go to Settings > Macros to see which macros exist, then check where they're used: templates, partial views and Rich Text Editor content.

  4. Don't forget Umbraco Forms. If editors inserted forms into rich text content with the Forms macro (for example "Insert Form with Theme"), those are macros too and need replacing.

  5. Check your code. Look at views and custom code that read these properties. The value converters for Nested Content and Grid Layout were removed in 14, so code that relies on them will need updating along with the content.

Step 2: Replace them before you upgrade

Switching the editor isn't the same as moving the content. If you change an existing data type to a different editor, the content already stored in it isn't converted to the new format, and it can be lost. Plan how the existing content will be moved, and always try it on a copy of your Live data first.

  • Media Picker (legacy), Nested Content and Grid Layout: set up the replacement editor and move the content across. On small sites this can be done by hand. On bigger sites, migration tooling saves a lot of work: Umbraco Deploy's import with migrations includes migrators for Nested Content, Grid Layout and the legacy Media Picker. See Import and Export with Migrations.

  • Macros: rebuild each one as a partial view or as a block in the Rich Text Editor, depending on how it's used. The two aren't identical, so check each macro's purpose before choosing.

  • Remove what you no longer need. Once the content has moved, delete the old data types and macros so nothing is left for the upgrade to trip over.

On Umbraco Cloud: make these changes locally or in a lower environment while still on 13, deploy them through your environments as normal, and confirm everything works before you start the major upgrade.

Signs that something was left behind

If you've already upgraded, these can point to a leftover from a removed feature:

  • Umbraco Deploy reports Unknown entity type "macro". This means schema files for macros from the old version are still in the project.

  • Deploy schema extraction fails on the upgraded environment and the error points to a document type or data type you haven't changed recently.

Don't delete schema files or edit the database to clear these yourself. The right fix depends on what's in your project, so ask Umboto to connect you with a human agent and include the full error message.

Recommended documentation


Last updated on November 3, 2026

Did this answer your question?