apache/pulsar · error · MetadataFormatException

Empty package metadata

Error message

Empty package metadata

What it means

Deserialization guard in PackageMetadataUtil.fromBytes: the byte payload for package metadata is null or empty, so no JSON (or legacy Java-serialized) metadata can be read from it; the bytes argument from the package storage read is the faulty input.

Source

Thrown at pulsar-package-management/core/src/main/java/org/apache/pulsar/packages/management/core/common/PackageMetadataUtil.java:77

    private PackageMetadataUtil() {
    }

    public static byte[] toBytes(PackageMetadata packageMetadata, boolean jsonSerializationEnabled) {
        if (jsonSerializationEnabled) {
            try {
                return JSON_WRITER.writeValueAsBytes(packageMetadata);
            } catch (IOException e) {
                throw new IllegalStateException("Failed to serialize package metadata as JSON", e);
            }
        }
        return SerializationUtils.serialize(packageMetadata);
    }

    public static PackageMetadata fromBytes(byte[] bytes, boolean allowLegacyJavaSerialization)
            throws MetadataFormatException {
        if (bytes == null || bytes.length == 0) {
            throw new MetadataFormatException("Empty package metadata");
        }
        int firstNonWhitespace = indexOfFirstNonWhitespace(bytes);
        if (firstNonWhitespace >= 0 && bytes[firstNonWhitespace] == JSON_LEADING_BYTE) {
            return readJson(bytes);
        }
        if (bytes.length >= 2 && bytes[0] == JAVA_MAGIC_BYTE_0 && bytes[1] == JAVA_MAGIC_BYTE_1) {
            if (!allowLegacyJavaSerialization) {
                throw new MetadataFormatException(
                        "Package metadata is in legacy Java serialization format but reading it is disabled. "
                                + "Enable packagesManagementAllowLegacyJavaSerialization or re-upload the package.");
            }
            return readLegacy(bytes);
        }
        throw new MetadataFormatException("Unrecognized package metadata format");
    }

    private static PackageMetadata readJson(byte[] bytes) throws MetadataFormatException {
        try {

View on GitHub (pinned to 820761864e)

Solutions

1. Upload non-empty package metadata with the package
2. Check the client isn't sending an empty metadata body

Example fix

// before
PackageMetadata m = PackageMetadataUtil.fromBytes(bytes, allow);
// after
if (bytes == null || bytes.length == 0) throw new IllegalArgumentException("missing metadata blob");
PackageMetadata m = PackageMetadataUtil.fromBytes(bytes, allow);

if (bytes == null || bytes.length == 0) {
    throw new IllegalArgumentException("package metadata blob is missing or empty; re-upload the package");
}

static boolean hasMetadata(byte[] bytes) {
    return bytes != null && bytes.length > 0;
}

try {
    PackageMetadata m = PackageMetadataUtil.fromBytes(bytes, allowLegacy);
} catch (MetadataFormatException e) {
    if ("Empty package metadata".equals(e.getMessage())) {
        // trigger re-upload path
    }
}

When it happens

Trigger: Reading package metadata from a metadata store entry that was never written, was truncated, or was deleted concurrently, then passing null/empty bytes to fromBytes.

Common situations: Corrupted or partially-written package entries in BookKeeper storage, a bug in the upload path that stored an empty payload, or reading metadata of a package that failed to upload.

Related errors

• Unrecognized package metadata format
• Invalid package domain: '${value}'
• Package metadata is in legacy Java serialization format but
• Failed to parse package metadata as JSON: ${message}
• Cursor %s mark-delete position %s is ahead of the last posit

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/8c73bf77b93f2621. Report an issue: GitHub.