{"record":{"id":"6a8b6cb0c8f3181b","repo":"HMCL-dev/HMCL","slug":"theme-background-url-must-be-http-or-https-url","errorCode":null,"errorMessage":"Theme background URL must be HTTP or HTTPS: ${url}","messagePattern":"Theme background URL must be HTTP or HTTPS: (.+?)","errorType":"validation","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java","lineNumber":1502,"sourceCode":"        }\n        if (!Files.isRegularFile(source)) {\n            throw new IOException(\"Theme background image does not exist: \" + source);\n        }\n\n        String entryName = \"assets/wallpapers/\" + sanitizePathSegment(source.getFileName().toString());\n        assets.add(new ThemePackAsset(source, entryName));\n        return new ThemeBackground.Image(entryName);\n    }\n\n    /// Downloads the current network background and exports it as a theme-pack image asset.\n    private static ThemeBackground.Image createCurrentNetworkBackgroundSource(\n            List<ThemePackAsset> assets,\n            List<Path> temporaryFiles,\n            ResolvedBackground background) throws IOException {\n        String url = requireNonBlank(background.networkImageUrl(), \"background.url\");\n        URI uri = NetworkUtils.toURI(url);\n        if (!NetworkUtils.isHttpUri(uri)) {\n            throw new IOException(\"Theme background URL must be HTTP or HTTPS: \" + url);\n        }\n\n        String entryName = \"assets/wallpapers/\" + networkBackgroundAssetName(uri);\n        if (background.networkImageCachePolicy() == NetworkBackgroundImageCachePolicy.ENABLED) {\n            try {\n                @Nullable Path cachedFile = new CacheFileTask(uri).run();\n                if (cachedFile != null && Files.isRegularFile(cachedFile)) {\n                    assets.add(new ThemePackAsset(cachedFile, entryName));\n                    return new ThemeBackground.Image(entryName);\n                }\n            } catch (Exception e) {\n                LOG.warning(\"Failed to cache theme background, falling back to direct download: \" + uri, e);\n            }\n        }\n\n        Path temporaryFile = Files.createTempFile(\"hmcl-theme-background-\", \".tmp\");\n        boolean success = false;\n        try {","sourceCodeStart":1484,"sourceCodeEnd":1520,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java#L1484-L1520","documentation":"Thrown by ThemePackManager when resolving a network background whose URL scheme is not HTTP or HTTPS (e.g. ftp:, file:, data:). The downloader only supports HttpURLConnection-based fetching, so non-HTTP(S) URIs are rejected before any download is attempted.","triggerScenarios":"Setting a theme background with networkImageUrl set to a non-HTTP(S) URI; NetworkUtils.toURI(url) parses it but NetworkUtils.isHttpUri(uri) returns false.","commonSituations":"Pasting a file:// or data:image/... URL into a theme's background.url field; using an ftp:// mirror link; authoring a manifest by hand with a localhost or custom-scheme URL.","solutions":["Replace the URL with an http:// or https:// link to the image.","If the image is local, use a background imagePath/file background instead of networkImageUrl.","If you need data-URI backgrounds, download the image and reference it as a local asset first."],"exampleFix":"// before\n\"background\": { \"url\": \"file:///home/user/wall.png\" }\n// after\n\"background\": { \"url\": \"https://example.com/wall.png\" }","handlingStrategy":"validation","validationCode":"URI uri = URI.create(url);\nif (!\"http\".equalsIgnoreCase(uri.getScheme()) && !\"https\".equalsIgnoreCase(uri.getScheme())) {\n    throw new IllegalArgumentException(\"background url must be http(s): \" + url);\n}","typeGuard":"static boolean isHttpUrl(String url) {\n    try {\n        String s = URI.create(url).getScheme();\n        return \"http\".equalsIgnoreCase(s) || \"https\".equalsIgnoreCase(s);\n    } catch (IllegalArgumentException e) { return false; }\n}","tryCatchPattern":null,"preventionTips":["Only use http:// or https:// links for network backgrounds.","Use local file backgrounds for images stored on disk instead of file:// URLs."],"tags":["theme-pack","url","validation","network"],"backgroundTag":"invalid-url","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}