apache/pulsar · error · SchemaSerializationException

'${fileDescriptorProto.getName()}' can't resolve dependency

Error message

'${fileDescriptorProto.getName()}' can't resolve  dependency '${dependency}'.

What it means

ProtobufNativeSchemaUtils.deserializeFileDescriptor rebuilds a FileDescriptor from its serialized proto and looks up each dependency in the local fileDescriptorCache. A dependency name missing from the cache triggers SchemaSerializationException listing the unresolvable dependency.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/schema/ProtobufNativeSchemaUtils.java:145

    }

    private static void deserializeFileDescriptor(FileDescriptorProto fileDescriptorProto,
                                                  Map<String, Descriptors.FileDescriptor> fileDescriptorCache,
                                                  Map<String, FileDescriptorProto> fileDescriptorProtoCache) {
        fileDescriptorProto.getDependencyList().forEach(dependencyFileDescriptorName -> {
            if (!fileDescriptorCache.containsKey(dependencyFileDescriptorName)) {
                FileDescriptorProto dependencyFileDescriptor =
                        fileDescriptorProtoCache.get(dependencyFileDescriptorName);
                deserializeFileDescriptor(dependencyFileDescriptor, fileDescriptorCache, fileDescriptorProtoCache);
            }
        });

        Descriptors.FileDescriptor[] dependencyFileDescriptors = fileDescriptorProto.getDependencyList().stream()
                .map(dependency -> {
            if (fileDescriptorCache.containsKey(dependency)) {
                return fileDescriptorCache.get(dependency);
            } else {
                throw new SchemaSerializationException("'" + fileDescriptorProto.getName()
                        + "' can't resolve  dependency '" + dependency + "'.");
            }
        }).toArray(Descriptors.FileDescriptor[]::new);

        try {
            Descriptors.FileDescriptor fileDescriptor = Descriptors.FileDescriptor
                    .buildFrom(fileDescriptorProto, dependencyFileDescriptors);
            fileDescriptorCache.put(fileDescriptor.getFullName(), fileDescriptor);
        } catch (Descriptors.DescriptorValidationException e) {
            e.printStackTrace();
            throw new SchemaSerializationException(e);
        }
    }

}

View on GitHub (pinned to 820761864e)

Solutions

Call deserializeFileDescriptor (or serialize) for each dependency descriptor first, then the top-level one
Bundle the generated classes/protos of all imported files so they can be registered locally
Simplify the proto to avoid external imports if dependency propagation is impractical

Example fix

// before
Descriptors.FileDescriptor fd = ProtobufNativeSchemaUtils.deserializeFileDescriptor(schemaData);
// after
ProtobufNativeSchemaUtils.deserializeFileDescriptor(depSchemaData); // seed dependency first
Descriptors.FileDescriptor fd = ProtobufNativeSchemaUtils.deserializeFileDescriptor(schemaData);

Defensive patterns

Strategy: validation

Validate before calling

Set<String> cached = getRegisteredDependencyNames();
List<String> missing = schemaData.getDependencyList().stream().filter(d -> !cached.contains(d)).collect(Collectors.toList());
if (!missing.isEmpty()) { throw new IllegalStateException("missing deps: " + missing); }

Try / catch

try { deserializeFileDescriptor(data); } catch (SchemaSerializationException e) { // register missing dependency descriptors, then retry }

Prevention

Seed the descriptor cache with all imports before deserializing
Ship generated classes for every imported proto
Assume schemas from other services may reference deps unknown locally

When it happens

Trigger: Deserializing schema data produced elsewhere (e.g. from a broker) when the consumer-side process never registered/seeded the dependency descriptors; consuming protobuf-native schemas from protos with imports.

Common situations: Multi-module projects where only the top-level descriptor is cached; schema written by a different service whose imports are unknown locally; ordering issues where deserialize is called before dependencies were registered.

Related errors

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