{"record":{"id":"1d2ddb82f209479a","repo":"HMCL-dev/HMCL","slug":"unrecognized-asset-object-name-in-asset-asset","errorCode":null,"errorMessage":"Unrecognized asset object ${name} in asset ${assetId} of version ${id}","messagePattern":"Unrecognized asset object (.+?) in asset (.+?) of version (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameInstance.java","lineNumber":328,"sourceCode":"            return reconstructAssets(assetId);\n        } catch (IOException | JsonParseException e) {\n            LOG.error(\"Unable to reconstruct asset directory\", e);\n            return getLayout().getAssetDirectory();\n        }\n    }\n\n    /// {@inheritDoc}\n    @Override\n    public Optional<Path> getAssetObject(String assetId, String name) throws IOException {\n        try {\n            @Nullable AssetObject assetObject = getAssetIndex(assetId).getObjects().get(name);\n            return assetObject != null\n                    ? Optional.of(getLayout().getAssetObject(assetObject))\n                    : Optional.empty();\n        } catch (IOException e) {\n            throw e;\n        } catch (Exception e) {\n            throw new IOException(\n                    \"Unrecognized asset object \" + name + \" in asset \" + assetId + \" of version \" + id,\n                    e);\n        }\n    }\n\n    /// Reconstructs virtual and legacy resource layouts for an asset index when required.\n    ///\n    /// @param assetId the asset index ID\n    /// @return the directory to supply at launch time\n    /// @throws IOException        if an asset cannot be copied\n    /// @throws JsonParseException if the asset index is malformed\n    private Path reconstructAssets(String assetId) throws IOException, JsonParseException {\n        Path assetsDir = getLayout().getAssetDirectory();\n        Path indexFile = getLayout().getAssetIndexFile(assetId);\n        Path virtualRoot = assetsDir.resolve(\"virtual\").resolve(assetId);\n\n        if (!Files.isRegularFile(indexFile)) {\n            return assetsDir;","sourceCodeStart":310,"sourceCodeEnd":346,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameInstance.java#L310-L346","documentation":"DefaultGameInstance.getAssetObject(name, assetId, id) resolves an asset object name from the asset index to a concrete file path. Any unexpected exception (beyond plain IOException) while looking up or reconstructing the asset object is wrapped in an IOException 'Unrecognized asset object <name> in asset <assetId> of version <id>'. It signals the asset index lacks an entry for the requested object or its stored metadata cannot be interpreted.","triggerScenarios":"Requesting an asset object whose hash/entry is absent from the parsed AssetIndex; AssetIndex throwing during virtual/legacy layout reconstruction; malformed asset index entries encountered while resolving the name.","commonSituations":"Mod or launcher code referencing a resource key not present in the version's asset index; mixing asset indexes between Minecraft versions (old version id with a newer assetId); partially repaired/corrupt asset index json missing entries.","solutions":["Confirm the asset object name exists in assets/indexes/<assetId>.json; if not, use the correct assetId for the Minecraft version being launched","Re-download the full asset index for that version so all entries are present","Catch the IOException, log name/assetId/id, and re-run asset verification (download missing assets) before retrying","Avoid mixing version ids and assetIds from different Minecraft versions when calling getAssetObject"],"exampleFix":"// before\nOptional<Path> obj = instance.getAssetObject(name, \"legacy\", \"1.7.10\");\n// after\n// use the assetId actually declared by the version json\nString assetId = versionJson.getAssets();\nOptional<Path> obj = instance.getAssetObject(name, assetId, \"1.7.10\");","handlingStrategy":"try-catch","validationCode":"AssetIndex idx = instance.getAssetIndex(assetId);\nboolean known = idx.getObject(name) != null; // verify entry exists before resolving path","typeGuard":null,"tryCatchPattern":"try {\n    Optional<Path> obj = instance.getAssetObject(name, assetId, versionId);\n} catch (IOException e) {\n    LOG.warning(\"Unresolved asset \" + name + \" for \" + assetId + \", running asset verification\");\n    verifyAndDownloadAssets(assetId);\n}","preventionTips":["Use the assetId declared by the version JSON, never a hardcoded one","Re-download the asset index rather than editing it","Log name/assetId/version on failure to speed diagnosis"],"tags":["minecraft-assets","lookup-failed","io"],"backgroundTag":"entity-not-found","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}