apache/pulsar · error · IllegalStateException

Failed to serialize package metadata as JSON

Error message

Failed to serialize package metadata as JSON

What it means

IllegalStateException thrown by PackageMetadataUtil.toBytes when Jackson's writeValueAsBytes fails to serialize PackageMetadata to JSON (jsonSerializationEnabled=true). Wraps the underlying JsonProcessingException (an IOException).

Source

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

                    + "java.lang.String;java.lang.Number;java.lang.Long;java.lang.Boolean;"
                    + "java.lang.Object;"
                    + "!*");

    private static final ObjectReader JSON_READER =
            ObjectMapperFactory.getMapper().reader().forType(PackageMetadata.class);
    private static final ObjectWriter JSON_WRITER = ObjectMapperFactory.getMapper().writer();

    private static final AtomicBoolean LEGACY_READ_WARNED = new AtomicBoolean(false);

    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. "

View on GitHub (pinned to 820761864e)

Solutions

1. Inspect the wrapped cause for the failing property and fix or annotate it in PackageMetadata.
2. Ensure the standard PackageMetadata class is used unmodified (no extra unserializable fields).
3. Verify a compatible jackson-databind version is on the classpath.
4. As a last resort set jsonSerializationEnabled=false, but that uses legacy Java serialization (see related errors).

Example fix

// before
class PackageMetadata { transient Object weirdField; } // non-serializable field
// after
class PackageMetadata { @JsonIgnore private transient Object weirdField; }

try {
    byte[] bytes = PackageMetadataUtil.toBytes(metadata, true);
} catch (IllegalStateException e) {
    // Jackson could not serialize; inspect e.getCause() for failing property
    log.error("Package metadata serialization failed", e.getCause());
    throw e;
}

When it happens

Trigger: Calling toBytes(metadata, true) with a PackageMetadata bean Jackson cannot serialize, e.g. a subclass with unsupported property types or a Jackson version mismatch.

Common situations: Custom builds that added non-serializable fields to PackageMetadata, missing/incorrect jackson-databind on the classpath, or mixing old clients that pass incompatible metadata objects.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

• Cannot convert ${m} to AVRO ${e.getMessage()}
• Failed to parse package metadata as JSON: ${message}
• Package Management Service is not enabled in the broker.
• RestException(conversionError)
• Incompatible schema: exists schema type %s, new schema type

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