{"record":{"id":"f24519cefd437bd7","repo":"apache/pulsar","slug":"unrecognized-package-metadata-format","errorCode":null,"errorMessage":"Unrecognized package metadata format","messagePattern":"Unrecognized package metadata format","errorType":"exception","errorClass":"MetadataFormatException","httpStatus":null,"severity":"error","filePath":"pulsar-package-management/core/src/main/java/org/apache/pulsar/packages/management/core/common/PackageMetadataUtil.java","lineNumber":91,"sourceCode":"\n    public static PackageMetadata fromBytes(byte[] bytes, boolean allowLegacyJavaSerialization)\n            throws MetadataFormatException {\n        if (bytes == null || bytes.length == 0) {\n            throw new MetadataFormatException(\"Empty package metadata\");\n        }\n        int firstNonWhitespace = indexOfFirstNonWhitespace(bytes);\n        if (firstNonWhitespace >= 0 && bytes[firstNonWhitespace] == JSON_LEADING_BYTE) {\n            return readJson(bytes);\n        }\n        if (bytes.length >= 2 && bytes[0] == JAVA_MAGIC_BYTE_0 && bytes[1] == JAVA_MAGIC_BYTE_1) {\n            if (!allowLegacyJavaSerialization) {\n                throw new MetadataFormatException(\n                        \"Package metadata is in legacy Java serialization format but reading it is disabled. \"\n                                + \"Enable packagesManagementAllowLegacyJavaSerialization or re-upload the package.\");\n            }\n            return readLegacy(bytes);\n        }\n        throw new MetadataFormatException(\"Unrecognized package metadata format\");\n    }\n\n    private static PackageMetadata readJson(byte[] bytes) throws MetadataFormatException {\n        try {\n            return JSON_READER.readValue(bytes);\n        } catch (IOException e) {\n            throw new MetadataFormatException(\"Failed to parse package metadata as JSON: \" + e.getMessage());\n        }\n    }\n\n    private static PackageMetadata readLegacy(byte[] bytes) throws MetadataFormatException {\n        try (ObjectInputStream ois = new ObjectInputStream(new ByteArrayInputStream(bytes))) {\n            ois.setObjectInputFilter(LEGACY_FILTER);\n            Object o = ois.readObject();\n            if (!(o instanceof PackageMetadata)) {\n                throw new MetadataFormatException(\"Unexpected metadata type: \"\n                        + (o == null ? \"null\" : o.getClass().getName()));\n            }","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-package-management/core/src/main/java/org/apache/pulsar/packages/management/core/common/PackageMetadataUtil.java#L73-L109","documentation":"MetadataFormatException thrown by PackageMetadataUtil.fromBytes when the payload neither starts with the JSON leading byte '{' nor the Java serialization magic bytes (0xAC 0xED), so its format cannot be recognized.","triggerScenarios":"Reading a metadata blob that was written by an incompatible writer, corrupted (e.g. compressed/encrypted/truncated), or has leading whitespace/bytes prepended before the JSON.","commonSituations":"Manual edits or migrations of package storage data, storing gzip-compressed metadata where raw bytes were expected, or a bug writing a BOM/extra bytes before the JSON payload.","solutions":["Re-upload the package to rewrite a valid JSON metadata blob.","Inspect the first bytes of the stored payload to identify the actual format (compression, BOM, corruption).","Check for proxy/storage layers that transform bytes (compression or encryption) and disable the transform.","If the data is legacy from an unknown source, restore it from a known-good backup or re-create the package."],"exampleFix":"// before\nbyte[] blob = gzip(decompress(raw)); // transformed payload stored\n// after\nbyte[] blob = raw; // store plain JSON bytes as the format expects","handlingStrategy":"validation","validationCode":"static boolean looksLikeKnownFormat(byte[] b) {\n    if (b == null || b.length == 0) return false;\n    if (b[0] == '{') return true;                     // JSON\n    return b.length >= 2 && b[0] == (byte) 0xAC && b[1] == (byte) 0xED; // java serialization\n}","typeGuard":null,"tryCatchPattern":"try {\n    PackageMetadata m = PackageMetadataUtil.fromBytes(bytes, allowLegacy);\n} catch (MetadataFormatException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Unrecognized\")) {\n        // dump first bytes hex for diagnosis, then restore from backup or re-upload\n    }\n}","preventionTips":["Never transform (compress/encrypt/BOM-prefix) package metadata blobs before storage.","Snapshot package storage before manual migrations.","Validate round-trip write/read in integration tests.","Treat unrecognized-format alerts as data-corruption incidents."],"tags":["deserialization","corruption","format","packages"],"backgroundTag":"unrecognized-data-format","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}