Troubleshooting: Classic to New Experience Migration Fails with "Error Parsing Logo for Migration"

Version Affected: 22.02 and later
 
 

Overview

Migrating a Classic realm to a New Experience realm can fail with the error "Error parsing logo for migration, check the error logs for more information."

Cause

This happens when one of the Logo Image file paths in the realm's web.config is incomplete or incorrect. The path must be corrected before the migration can succeed.

Resolution

1. Decrypt the realm's web.config.
2. Open web.config in a text editor and find the PortalLogoPath key. Check that its value is a complete, valid path — including the relative or absolute path, the file name, and the file extension. For example, the following value is not a valid path and causes the migration to fail:

<add key="PortalLogoPath" value="~\images\" />

3. Open the realm in Web Admin or Admin Console and select an image directly (Application Logo on the realm's Overview tab). Alternatively, update the PortalLogoPath value in web.config directly to point to a valid file — this option has more room for human error and is not recommended.

To confirm a path is valid, open it in a web browser by appending the relative path to the realm's URL — for example, if the relative path is ~/images/SecureAuth_Logo_OnBlack.png, browse to https://localhost/SecureAuth5/images/SecureAuth_Logo_OnBlack.png. If the path is valid, the image loads in the browser. If the path is not valid, the browser shows an error page instead.

Not valid (path in web.config is ~\images\) — browsing to the folder itself returns an HTTP 403.14 Forbidden error, since directory browsing is not enabled:

Or, if the path in web.config points at a file that doesn't exist (for example, ~/images/image_which_does_not_exist.png), browsing to it returns an HTTP 404 Not Found error:

Valid (path in web.config is ~/Images/SecureAuth_Logo_OnBlack.png) — the image loads directly in the browser:

4. If correcting the PortalLogoPath value does not resolve the migration failure, also check the LogoPath and EmailLogoPath keys in web.config to confirm they are correct. These two keys being invalid has not been seen to cause this specific error, but are worth checking regardless:

<add key="LogoPath" value="~/Images/SecureAuth_Logo_OnBlack.png" />
<add key="EmailLogoPath" value="~/Images/SecureAuth_Logo_OnBlack.png" />

Special Considerations

When a new Classic realm is created using an existing Classic realm as its template, the new realm takes on the same settings — including an incorrect LogoPath value, if the template realm has one. If the template realm's file path is incorrect, correct it on the template realm first, before creating any further Classic realms from it.
 
 

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.