nopSolutions/nopCommerce · error · Exception

A theme descriptor '{descriptionFile}' has no system name

Error message

A theme descriptor '{descriptionFile}' has no system name

What it means

Thrown by ThemeProvider while scanning theme description files: for each themeDescription.json file under the themes directory it parses the descriptor and throws if themeDescriptor.SystemName is null/empty. Parsing a JSON file that omits or blanks the 'SystemName' field triggers it.

Source

Thrown at src/Libraries/Nop.Services/Themes/ThemeProvider.cs:46

        var fileProvider = CommonHelper.DefaultFileProvider;

        //load all theme descriptors
        _themeDescriptors = new Dictionary<string, ThemeDescriptor>(StringComparer.InvariantCultureIgnoreCase);

        var themeDirectoryPath = fileProvider.MapPath(NopThemeDefaults.ThemesPath);
        foreach (var descriptionFile in fileProvider.GetFiles(themeDirectoryPath, NopThemeDefaults.ThemeDescriptionFileName, false))
        {
            var text = await fileProvider.ReadAllTextAsync(descriptionFile, Encoding.UTF8);
            if (string.IsNullOrEmpty(text))
                continue;

            //get theme descriptor
            var themeDescriptor = GetThemeDescriptorFromText(text);

            //some validation
            if (string.IsNullOrEmpty(themeDescriptor?.SystemName))
                throw new Exception($"A theme descriptor '{descriptionFile}' has no system name");

            _themeDescriptors.TryAdd(themeDescriptor.SystemName, themeDescriptor);
        }
    }

    /// <summary>
    /// Get theme descriptor from the description text
    /// </summary>
    /// <param name="text">Description text</param>
    /// <returns>Theme descriptor</returns>
    public ThemeDescriptor GetThemeDescriptorFromText(string text)
    {
        //get theme description from the JSON file
        var themeDescriptor = JsonConvert.DeserializeObject<ThemeDescriptor>(text);

        //some validation
        if (_themeDescriptors.ContainsKey(themeDescriptor.SystemName))
            throw new Exception($"A theme with '{themeDescriptor.SystemName}' system name is already defined");

View on GitHub (pinned to 64bdf2ff08)

Solutions

1. Open the offending file at the path in the error message and add a non-empty unique SystemName.
2. Ensure SystemName is unique across all themes (see error 168).
3. Remove the half-installed theme folder if it is not meant to be used.

Example fix

// before (themeDescription.json)
{ "FriendlyName": "My Theme" }
// after
{ "SystemName": "MyTheme", "FriendlyName": "My Theme" }

var desc = JsonConvert.DeserializeObject<ThemeDescriptor>(text);
if (string.IsNullOrWhiteSpace(desc?.SystemName))
    // skip/fix this file rather than letting ThemeProvider throw at startup

static bool HasValidSystemName(string json)
{
    var d = JsonConvert.DeserializeObject<ThemeDescriptor>(json);
    return !string.IsNullOrWhiteSpace(d?.SystemName);
}

try { await _themeProvider.InitializeAsync(); }
catch (Exception ex) when (ex.Message.Contains("no system name"))
{ logger.Error($"Invalid theme descriptor: {ex.Message}", ex); }

When it happens

Trigger: A theme folder under wwwroot/themes (or the configured themes path) contains a themeDescription.json whose SystemName property is missing, empty, or whitespace. Thrown during theme initialization at app startup or first theme enumeration.

Common situations: Copying a theme folder and forgetting to set a unique SystemName; hand-editing themeDescription.json and dropping the field; a theme package with a malformed descriptor.

Related errors

• A theme with '{themeDescriptor.SystemName}' system name is a
• One page checkout is disabled
• Anonymous checkout is not allowed
• Selected shipping method can't be loaded
• Email is not valid.

AI-assisted analysis of nopSolutions/nopCommerce@64bdf2ff08 (2026-08-13). Data as JSON: /api/errors/e83d8e1b6aa96cb3. Report an issue: GitHub.