What causes "Schema Registry is not set for cluster ${clusterName}" in provectus/kafka-ui?

Add a schemaRegistry URL to the cluster config, e.g. schemaRegistry: http://schema-registry:8081

provectus/kafka-ui · error · ValidationException

Schema Registry is not set for cluster

Error message

Schema Registry is not set for cluster ${clusterName}

What it means

SchemasController.getCluster wraps the base cluster lookup and requires the cluster to have a Schema Registry client configured. If the cluster config lacks schemaRegistry, every schema-related endpoint (compatibility check, create/delete schema, list schemas) throws ValidationException.

Solutions

Add a schemaRegistry URL to the cluster config, e.g. schemaRegistry: http://schema-registry:8081
Verify the YAML nesting puts schemaRegistry inside the correct cluster entry
Deploy/run a Schema Registry service and confirm it's reachable from kafka-ui

Example fix

// before
kafka:
  clusters:
    - name: dev
      bootstrapServers: broker1:9092
// after
kafka:
  clusters:
    - name: dev
      bootstrapServers: broker1:9092
      schemaRegistry: http://schema-registry:8081

Defensive patterns

Strategy: try-catch

Validate before calling

cluster_cfg = get_cluster_config(name)
if not cluster_cfg.get('schemaRegistry'):
    raise ValueError(f'Schema Registry not configured for {name}')

Try / catch

try {
  schemas = schemasApi.listSchemas(clusterName);
} catch (ValidationException e) {
  if (e.getMessage().contains("Schema Registry is not set")) {
    showClusterSetupHint(); // guide user to add schemaRegistry config
  }
}

Prevention

Include schemaRegistry URL whenever the cluster uses Schema Registry subjects
Disable/hide schema features in the UI for clusters without one
Health-check the schema registry endpoint at startup

When it happens

Trigger: Calling any /api/clusters/{c}/schemas endpoint for a cluster whose config has no `schemaRegistry` entry (URL omitted or blank).

Common situations: Connecting to a plain Kafka cluster without Schema Registry installed; adding schemaRegistry under the wrong YAML level so it isn't picked up; Schema Registry host unreachable at startup so the client is not created.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of provectus/kafka-ui@83b5a60cc0 (2026-09-08). Data as JSON: /api/errors/8a43dd86c49b5cf2. Report an issue: GitHub.

Appendix: source

Thrown at kafka-ui-api/src/main/java/com/provectus/kafka/ui/controller/SchemasController.java:43

import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

@RestController
@RequiredArgsConstructor
@Slf4j
public class SchemasController extends AbstractController implements SchemasApi {

  private static final Integer DEFAULT_PAGE_SIZE = 25;

  private final KafkaSrMapper kafkaSrMapper = new KafkaSrMapperImpl();

  private final SchemaRegistryService schemaRegistryService;

  @Override
  protected KafkaCluster getCluster(String clusterName) {
    var c = super.getCluster(clusterName);
    if (c.getSchemaRegistryClient() == null) {
      throw new ValidationException("Schema Registry is not set for cluster " + clusterName);
    }
    return c;
  }

  @Override
  public Mono<ResponseEntity<CompatibilityCheckResponseDTO>> checkSchemaCompatibility(
      String clusterName, String subject, @Valid Mono<NewSchemaSubjectDTO> newSchemaSubjectMono,
      ServerWebExchange exchange) {
    var context = AccessContext.builder()
        .cluster(clusterName)
        .schema(subject)
        .schemaActions(SchemaAction.VIEW)
        .operationName("checkSchemaCompatibility")
        .build();

    return validateAccess(context).then(
        newSchemaSubjectMono.flatMap(subjectDTO ->
                schemaRegistryService.checksSchemaCompatibility(

View on GitHub (pinned to 83b5a60cc0)