Skip to main content

Resolving 404 Errors and BootFailedException During Umbraco v17 Upgrades

This guide addresses how to resolve database-level key collisions and front-end "Page Not Found" errors caused by breaking changes in version 17.

Written by Joana Knobbe

Product: Umbraco CMS Version: v17
​
During the upgrade process to Umbraco v17, duplicate URL aliases or incorrect configuration of moved packages can cause boot failures and site-wide routing issues.

Issue: Users upgrading to v17 may encounter two primary obstacles:

  1. BootFailedException: An error stating "An item with the same key has already been added" during the unattended upgrade process, specifically within the DocumentUrlAliasRepository.

  2. Persistent 404 Errors: After resolving boot issues, the front end returns a 404 "Page Not Found" error for all pages, even if the backoffice is accessible.

Solution:

1. Resolve Duplicate URL Aliases

If the upgrade fails with a BootFailedException, it is often due to case-insensitive duplicates in the umbracoUrlAlias property.

  • Identify Duplicates: Run the following SQL query to find nodes where multiple aliases normalize to the same value:
    ​

    SELECT cv.nodeId, LOWER(LTRIM(RTRIM(value))) AS NormalizedAlias, COUNT(*) FROM umbracoPropertyData pd JOIN cmsPropertyType pt ON pd.propertyTypeId = pt.id JOIN umbracoContentVersion cv ON pd.versionId = cv.id CROSS APPLY STRING_SPLIT(pd.textValue, ',') WHERE pt.alias = 'umbracoUrlAlias' AND pd.textValue IS NOT NULL GROUP BY cv.nodeId, LOWER(LTRIM(RTRIM(value))) HAVING COUNT(*) > 1;

  • Manual Cleanup: Locate the affected nodes in the Umbraco Backoffice and ensure the "Short URL Alias" (or umbracoUrlAlias) values are unique and do not contain case-sensitive duplicates (e.g., avoid having both aoe and AOE).
    ​

2. Address Breaking Changes in v17 (The 404 Solution)

If you see the backoffice but the front end returns 404 errors, it is likely because you have missed steps in the v17 Breaking Changes documentation. Specifically:

  • Package Separation: In v17, InMemoryAuto models builder and Razor runtime compilation have moved into their own separate NuGet packages.

  • Project File Cleanup: You must remove legacy settings related to these features from your .csproj file. Even if you don't use InMemoryAuto, legacy configuration left in the project file can interfere with view compilation.

  • Intellisense and Views: Failing to remove these old settings can prevent views from rendering properly, causing the routing engine to fail and return a generic 404. After removing the legacy settings and installing the new packages, perform a clean and rebuild.

3. Verify Web Routing Configuration

Ensure your appsettings.json (or environment-specific JSON) contains a correctly formatted UmbracoApplicationUrl:

  • The URL must be fully qualified, including the scheme and a Top-Level Domain (TLD) (e.g., https://localhost:44370/ or https://www.example.com/). Note that localhost without a trailing slash or port can sometimes cause issues in v17 environments.

Article last update date: 15-05-2026

Did this answer your question?