halo-dev/halo · error · TemplateInputException

Exception loading messages file

Error message

Exception loading messages file

What it means

readMessagesResource() opens a Reader on a theme message properties file and calls Properties.load(reader). If load() throws any exception (malformed file: bad Unicode escape, illegal escape, IO failure mid-read), it is wrapped in a TemplateInputException 'Exception loading messages file' and aborts theme message resolution. A null Reader returns null earlier and does NOT throw, so this error implies the file exists but is unreadable/malformed.

Source

Thrown at application/src/main/java/run/halo/app/theme/message/ThemeMessageResolutionUtils.java:127

        return resourceNames;
    }

    private static String getResourceName(String name) {
        return LOCATION + "/" + name + PROPERTIES_FILE_EXTENSION;
    }

    private static Properties readMessagesResource(final Reader propertiesReader) {
        if (propertiesReader == null) {
            return null;
        }
        final Properties properties = new Properties();
        try (propertiesReader) {
            // Note Properties#load(Reader) this is JavaSE 6 specific, but Thymeleaf 3.0 does
            // not support Java 5 anymore...
            properties.load(propertiesReader);
        } catch (final Exception e) {
            throw new TemplateInputException("Exception loading messages file", e);
        }
        // ignore errors closing
        return properties;
    }
}

View on GitHub (pinned to d2f5165f9c)

Solutions

1. Open the offending theme messages_*.properties and fix the malformed escape sequence (the wrapped cause names the line).
2. Re-save the file as ISO-8859-1 (Properties.load(Reader) expects the Reader's encoding) or valid UTF-8 with proper \uXXXX escapes for non-ASCII.
3. Reinstall the theme from a known-good archive if the file got corrupted.
4. Check filesystem permissions/health if the cause is an IOException.

Example fix

# before (broken unicode escape in messages_en.properties)
#   greeting = Hello \u00WorId
# after
#   greeting = Hello World

// Validate a theme messages file parses before deploying:
Properties p = new Properties();
try (Reader r = Files.newBufferedReader(path)) {
    p.load(r);
} catch (Exception e) {
    throw new IllegalStateException("Malformed theme messages file " + path + ": " + e.getMessage(), e);
}

try {
    Properties msg = readMessagesResource(reader);
} catch (TemplateInputException e) {
    log.error("Skipping malformed theme messages file: {}", e.getCause().getMessage());
    // fall back to default messages instead of aborting the whole render
}

When it happens

Trigger: A theme bundles a messages_<lang>.properties (or messages_default.properties) that is present but cannot be parsed: invalid \u escapes, stray bytes, or an I/O error while reading. Thrown during theme message-bundle resolution for the request locale.

Common situations: Hand-edited properties file with a broken escape sequence; file saved as non-Latin1/non-UTF-8 with raw high bytes that break Properties.load; truncated file on disk; file-system read error.

Related errors

• Locale "{}" cannot be used as it does not specify a language
• Unable to complete the request because the theme configMapNa
• Explicit ESM output requires a simple stable spec.requires t
• Unable to complete the request because the plugin configMapN
• The name from the request body does not match the plugin con

AI-assisted analysis of halo-dev/halo@d2f5165f9c (2026-08-14). Data as JSON: /api/errors/fb916024d514d66e. Report an issue: GitHub.