HMCL-dev/HMCL · error · IOException

Theme-pack asset source is not a regular file:

Error message

Theme-pack asset source is not a regular file:

What it means

Thrown by ThemePackExporter.validateAssets (invoked from export) when an asset's declared source path exists but is not a regular file — typically a directory. Exporting would otherwise zip a non-file source, so the exporter validates every asset source and its readability before the target archive is written.

Solutions

  1. Change the asset source to point to an actual file, not a directory.
  2. If a directory was intended, enumerate it and create one ThemePackAsset per file.
  3. Verify with Files.isRegularFile(path) before building the asset list.
  4. Check symlink targets — resolve to the final target and confirm it is a regular file.

Example fix

// before
var asset = ThemePackAsset.of("background.png", Path.of("assets/wallpapers"));
// after
var asset = ThemePackAsset.of("background.png", Path.of("assets/wallpapers/default.png"));
Defensive patterns

Strategy: validation

Validate before calling

for (ThemePackAsset a : assets) {
    Path f = a.source().file();
    if (f != null && !Files.isRegularFile(f)) {
        throw new IllegalArgumentException("Not a regular file: " + f);
    }
}

Try / catch

try { ThemePackExporter.export(pack, assets, out); } catch (IOException e) { if (e.getMessage().startsWith("Theme-pack asset source is not a regular file")) fixAssetPaths(); throw e; }

Prevention

When it happens

Trigger: Calling ThemePackExporter.export with a ThemePackAsset whose source().file() points to a directory (or special file like a socket/fifo) instead of a regular file.

Common situations: Pointing a background asset at a directory of wallpapers instead of a single image, resolving paths through symlinks to directories, or build scripts passing a folder where a file is expected.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

AI-assisted analysis of HMCL-dev/HMCL@24702dc5a0 (2026-09-10). Data as JSON: /api/errors/8f5b4a46837f33c4. Report an issue: GitHub.

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackExporter.java:105

            try {
                Files.deleteIfExists(temporaryFile);
            } catch (IOException suppressed) {
                e.addSuppressed(suppressed);
            }
            throw e;
        }
    }

    /// Validates all asset entries and source files before the zip is written.
    private static void validateAssets(List<ThemePackAsset> assets) throws IOException {
        Set<String> entries = new HashSet<>();
        entries.add(MANIFEST_ENTRY);

        for (ThemePackAsset asset : assets) {
            Objects.requireNonNull(asset);
            @Nullable Path sourceFile = asset.source().file();
            if (sourceFile != null && !Files.isRegularFile(sourceFile)) {
                throw new IOException("Theme-pack asset source is not a regular file: " + sourceFile);
            }
            try (InputStream ignored = asset.source().openStream()) {
                // Validate readability before writing the target zip.
            }
            if (!entries.add(asset.entryName())) {
                throw new IllegalArgumentException("Duplicate theme-pack zip entry: " + asset.entryName());
            }
        }
    }
}

View on GitHub (pinned to 24702dc5a0)