{"record":{"id":"4e4da8e15ab34309","repo":"apache/pulsar","slug":"runtimeexception-conversionerror","errorCode":null,"errorMessage":"RuntimeException(conversionError)","messagePattern":"RuntimeException\\(conversionError\\)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/SchemasResourceBase.java","lineNumber":210,"sourceCode":"    protected String domain() {\n        return \"persistent\";\n    }\n\n    private static GetSchemaResponse convertSchemaAndMetadataToGetSchemaResponse(SchemaAndMetadata schemaAndMetadata) {\n        try {\n            String schemaData;\n            if (schemaAndMetadata.schema.getType() == SchemaType.KEY_VALUE) {\n                schemaData = DefaultImplementation.getDefaultImplementation().convertKeyValueSchemaInfoDataToString(\n                        DefaultImplementation.getDefaultImplementation()\n                                .decodeKeyValueSchemaInfo(schemaAndMetadata.schema.toSchemaInfo()));\n            } else {\n                schemaData = new String(schemaAndMetadata.schema.getData(), StandardCharsets.UTF_8);\n            }\n            return GetSchemaResponse.builder().version(getLongSchemaVersion(schemaAndMetadata.version))\n                    .type(schemaAndMetadata.schema.getType()).timestamp(schemaAndMetadata.schema.getTimestamp())\n                    .data(schemaData).properties(schemaAndMetadata.schema.getProps()).build();\n        } catch (IOException conversionError) {\n            throw new RuntimeException(conversionError);\n        }\n    }\n\n    protected GetSchemaResponse convertToSchemaResponse(SchemaAndMetadata schema) {\n        if (isNull(schema)) {\n            throw new RestException(Response.Status.NOT_FOUND.getStatusCode(), \"Schema not found\");\n        } else if (schema.schema.isDeleted()) {\n            throw new RestException(Response.Status.NOT_FOUND.getStatusCode(), \"Schema is deleted\");\n        }\n        return convertSchemaAndMetadataToGetSchemaResponse(schema);\n    }\n\n    protected GetAllVersionsSchemaResponse convertToAllVersionsSchemaResponse(List<SchemaAndMetadata> schemas) {\n        if (isNull(schemas)) {\n            throw new RestException(Response.Status.NOT_FOUND.getStatusCode(), \"Schemas not found\");\n        } else {\n            return GetAllVersionsSchemaResponse.builder()\n                    .getSchemaResponses(schemas.stream()","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/SchemasResourceBase.java#L192-L228","documentation":"convertSchemaAndMetadataToGetSchemaResponse converts a stored SchemaAndMetadata into a GetSchemaResponse whose data is the schema definition as a UTF-8 String. If reading/converting the stored schema bytes throws IOException (the declared checked exception from schema.getData/serialization plumbing), it is rethrown as an unchecked RuntimeException, which propagates out of the admin GET schema handlers as an HTTP 500.","triggerScenarios":"GET /admin/v2/schemas/{tenant}/{namespace}/{topic}/schema (or /latest, /versions/{version}) when the broker fails to deserialize or convert the stored schema definition — e.g. corrupt schema ledger/bookkeeper entry or an internal conversion path that declares IOException.","commonSituations":"Underlying schema storage corruption (BookKeeper ledger truncation/loss); schema written by an incompatible older broker; transient storage read failures surfacing as conversion IOExceptions; a schema type registered server-side that the conversion code path can't handle.","solutions":["Inspect broker logs for the RuntimeException's cause (the IOException stack trace) to identify whether storage read or schema deserialization failed.","Verify schema storage health (BookKeeper ledgers backing the schema store); restore from backup or re-upload the schema via PUT if entries are corrupted.","Delete the bad schema version (deleteSchema) and re-register a valid schema to replace the corrupt entry.","If it reproduces on a healthy cluster, capture broker/client versions and file an issue — wrapping an IOException as a bare RuntimeException is a known rough edge in this code path."],"exampleFix":"// server-side hardening in convertSchemaAndMetadataToGetSchemaResponse\n// before\n} catch (IOException conversionError) {\n    throw new RuntimeException(conversionError);\n}\n// after\n} catch (IOException conversionError) {\n    throw new RestException(Response.Status.INTERNAL_SERVER_ERROR.getStatusCode(),\n        \"Failed to convert stored schema: \" + conversionError.getMessage());\n}","handlingStrategy":"try-catch","validationCode":"// Verify schema is readable before use\nSchemaAndMetadata meta = /* fetched */;\nif (meta != null && meta.schema != null && meta.schema.getData() != null) {\n    String data = new String(meta.schema.getData(), StandardCharsets.UTF_8);\n    if (data.isEmpty()) throw new IllegalStateException(\"Empty stored schema data\");\n}","typeGuard":"static boolean isReadableSchema(SchemaAndMetadata m) {\n    return m != null && m.schema != null && m.schema.getData() != null && m.schema.getData().length > 0;\n}","tryCatchPattern":"try {\n    GetSchemaResponse resp = admin.schemas().getSchemaInfo(topic);\n} catch (PulsarAdminException e) {\n    if (e.getStatusCode() >= 500) {\n        log.error(\"Broker failed converting stored schema; check storage health\", e);\n    }\n    throw e;\n} catch (RuntimeException e) {\n    log.error(\"Unexpected schema conversion failure: {}\", e.getMessage(), e);\n    throw e;\n}","preventionTips":["Monitor BookKeeper/schema-store health; most 500s here trace to storage read errors.","Re-upload schemas after broker version migrations if conversion paths changed.","Set alerts on admin GET schema 500s to catch corruption early.","Avoid deleting underlying ledgers backing the schema store."],"tags":["pulsar","schema-registry","internal-error","ioexception"],"backgroundTag":"schema-conversion-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}