d2phap/ImageGlass · error · ArgumentException

IGE: Unable to load '{themeFolderName}' theme pack. Please m

Error message

IGE: Unable to load '{themeFolderName}' theme pack. Please make sure '{themeConfigPath}' file is valid.

What it means

Thrown by Config_Static.LoadThemeAsync (the theme-load flow) when the requested theme pack fails validation (th.IsValid is false) after exhausting all fallbacks, including the default theme, and throwIfThemeInvalid is true. The message names the theme folder and the path of the theme config file (theme.json) so the user can find and fix it.

Source

Thrown at source/ImageGlass.Lib/Settings/Config_Static.cs:992

        if (!th.IsValid)
        {
            // 2. look for theme pack in the base dir
            var baseThemeConfigPath = BHelper.BaseDir(Dir.Themes, themeFolderName);
            th = await new IgTheme().LoadAsync(baseThemeConfigPath);

            // 3. cannot find theme, use fall back theme
            if (!th.IsValid && useFallBackTheme)
            {
                // 4. load default theme
                baseThemeConfigPath = BHelper.BaseDir(Dir.Themes, Const.DEFAULT_THEME);
                th = await new IgTheme().LoadAsync(baseThemeConfigPath);
            }
        }

        // 5. throw error if theme is invalid
        if (!th.IsValid && throwIfThemeInvalid)
        {
            throw new ArgumentException($"IGE: Unable to load '{themeFolderName}' theme pack. " +
                $"Please make sure '{themeConfigPath}' file is valid.", nameof(themeFolderName));
        }

        return th;
    }


    /// <summary>
    /// Gets control layout position.
    /// </summary>
    public static LayoutPosition GetControlLayout(LayoutControl control)
    {
        var defaultPos = control == LayoutControl.Toolbar
            ? LayoutPosition.Top
            : LayoutPosition.Bottom;


        // 1. read control's layouts from setting

View on GitHub (pinned to 4a3c4fecef)

Solutions

1. Open the theme.json at the printed themeConfigPath and validate it is well-formed JSON with all required IgTheme fields.
2. Re-install or re-download the theme pack; if the folder was renamed, restore the original name referenced by Config.Theme.
3. If the default theme is also failing, reinstall ImageGlass to restore the shipped default theme pack under Dir.Themes/Const.DEFAULT_THEME.
4. Switch Config.Theme back to the default theme name (or delete the user theme preference) so startup uses the shipped default.

Example fix

// before
if (!th.IsValid && throwIfThemeInvalid)
    throw new ArgumentException($"IGE: Unable to load '{themeFolderName}' theme pack. " +
        $"Please make sure '{themeConfigPath}' file is valid.", nameof(themeFolderName));

// after — include the specific validation failure so the user knows what to fix
if (!th.IsValid && throwIfThemeInvalid)
    throw new ArgumentException(
        $"IGE: Unable to load '{themeFolderName}' theme pack. " +
        $"Please make sure '{themeConfigPath}' file is valid. " +
        $"Validation errors: {string.Join("; ", th.ValidationErrors)}",
        nameof(themeFolderName));

// Before requesting a theme, confirm the folder and theme.json exist.
var themeConfigPath = BHelper.BaseDir(Dir.Themes, themeFolderName, Const.THEME_CONFIG_FILE);
if (!File.Exists(themeConfigPath)) return GetDefaultTheme();
var json = File.ReadAllText(themeConfigPath);
if (string.IsNullOrWhiteSpace(json) || JsonDocument.Parse(json).RootElement.ValueKind != JsonValueKind.Object)
    return GetDefaultTheme();

static bool ThemeConfigLooksValid(string path)
{
    if (!File.Exists(path)) return false;
    try { using var d = JsonDocument.Parse(File.ReadAllText(path)); return d.RootElement.ValueKind == JsonValueKind.Object; }
    catch { return false; }
}

try { return await Config.LoadThemeAsync(name, throwIfThemeInvalid: true); }
catch (ArgumentException ex) when (ex.Message.Contains("Unable to load") && ex.Message.Contains("theme pack"))
{ _log.Warn($"Theme load failed: {ex.Message}"); return await Config.LoadThemeAsync(Const.DEFAULT_THEME, throwIfThemeInvalid: false); }

When it happens

Trigger: Produced at Config_Static.cs:992 when th.IsValid is still false after: (1) loading the requested theme failed, (2) the default-theme fallback (if useFallBackTheme) also produced an invalid theme, and (3) the caller requested throwIfThemeInvalid. Reached via theme switching or startup theme load.

Common situations: User-installed a corrupt or partial theme pack (missing theme.json, missing required color keys, malformed JSON); a theme folder renamed/moved breaking the relative path; an incompatible theme built for an older ImageGlass theme schema (missing new required fields); the default theme pack itself was deleted from the Themes directory so the fallback also failed.

Related errors

• IGE: Could not parse merged config.
• Unable to load '{themeFolderName}' theme pack. Please make s
• IGE: Metadata too large: {contentLength} bytes.
• Button ID required.
• A button with the ID '{0}' has already been defined. Please

AI-assisted analysis of d2phap/ImageGlass@4a3c4fecef (2026-08-13). Data as JSON: /api/errors/120ca6d63eb975c0. Report an issue: GitHub.