apache/pulsar · error · SchemaSerializationException

Can't get accurate schema information for topic ${topicName}

Error message

Can't get accurate schema information for topic ${topicName}using AutoConsumeSchema because SchemaInfoProvider is not set yet

What it means

AutoConsumeSchema needs the broker's SchemaInfoProvider to look up a schema for an unknown schema version. If the provider was never set (schemaInfoProvider == null) and a new schema version is encountered, it throws SchemaSerializationException because it cannot resolve the schema for that version.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/schema/AutoConsumeSchema.java:341

     * @see #atSchemaVersion(byte[])
     */
    public Schema<?> unwrapInternalSchema(byte[] schemaVersion) {
        fetchSchemaIfNeeded(BytesSchemaVersion.of(schemaVersion));
        return getInternalSchema(schemaVersion);
    }

    /**
     * It may happen that the schema is not loaded but we need it, for instance in order to call getSchemaInfo()
     * We cannot call this method in getSchemaInfo, because getSchemaInfo is called in many
     * places and we will introduce lots of deadlocks.
     */
    public void fetchSchemaIfNeeded(SchemaVersion schemaVersion) throws SchemaSerializationException {
        if (schemaVersion == null) {
            schemaVersion = BytesSchemaVersion.of(new byte[0]);
        }
        if (!schemaMap.containsKey(schemaVersion)) {
            if (schemaInfoProvider == null) {
                throw new SchemaSerializationException("Can't get accurate schema information for topic " + topicName
                        + "using AutoConsumeSchema because SchemaInfoProvider is not set yet");
            } else {
                SchemaInfo schemaInfo = null;
                try {
                    schemaInfo = schemaInfoProvider.getSchemaByVersion(schemaVersion.bytes()).get();
                    if (schemaInfo == null) {
                        // schemaless topic
                        schemaInfo = BytesSchema.of().getSchemaInfo();
                    }
                } catch (InterruptedException | ExecutionException e) {
                    if (e instanceof InterruptedException) {
                        Thread.currentThread().interrupt();
                    }
                    log.error().attr("topic", topicName).log("Can't get last schema for topic using AutoConsumeSchema");
                    throw new SchemaSerializationException(e.getCause());
                }
                // schemaInfo null means that there is no schema attached to the topic.
                Schema<?> schema = generateSchema(schemaInfo);

View on GitHub (pinned to 820761864e)

Solutions

Attach a SchemaInfoProvider via schema.setSchemaInfoProvider(...) before decoding
Use Schema.AUTO_CONSUME() through the normal consumer builder so the client wires the provider automatically
Catch SchemaSerializationException and fall back to raw byte consumption

Example fix

// before
AutoConsumeSchema s = new AutoConsumeSchema();
GenericRecord r = s.decode(bytes, version); // throws
// after
AutoConsumeSchema s = new AutoConsumeSchema();
s.setSchemaInfoProvider(myProvider);
s.fetchSchemaIfNeeded(BytesSchemaVersion.of(version));
GenericRecord r = s.decode(bytes, version);

Defensive patterns

Strategy: validation

Validate before calling

if (autoSchema.getSchemaInfoProvider() == null) {
    throw new IllegalStateException("Attach a SchemaInfoProvider before decoding with AutoConsumeSchema");
}

Type guard

boolean hasProvider(AutoConsumeSchema s) {
    return s != null && s.getSchemaInfoProvider() != null;
}

Try / catch

try {
    schema.fetchSchemaIfNeeded(version);
} catch (SchemaSerializationException e) {
    // fall back to raw byte consumption or attach a provider and retry
}

Prevention

Construct AutoConsumeSchema via Schema.AUTO_CONSUME() so the client wires the provider
When instantiating manually, always call setSchemaInfoProvider first
In offline/test contexts, provide a static SchemaInfoProvider backed by known schemas

When it happens

Trigger: fetchSchemaIfNeeded is invoked (from decode, atSchemaVersion, or unwrapInternalSchema) with a schema version absent from schemaMap while the schema was constructed without a SchemaInfoProvider — typically a manually instantiated AutoConsumeSchema rather than one wired by the consumer.

Common situations: Building AutoConsumeSchema by hand in tests or tools without calling setSchemaInfoProvider; using the schema outside a real consumer connection so no provider is attached.

Related errors

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