feat[UX-664]: add detailed schema compatibility error messages (#2031)

* feat: add detailed schema compatibility error messages

Parse and display structured error details from schema registry when
protobuf schema validation fails. Previously returned only boolean
compatibility status without explanation of why schemas are incompatible.

Backend changes:
- Add schemaRegValidationError struct with errorType and description
- Parse verbose compatibility messages from schema registry API
- Handle invalid JSON format returned by schema registry

Frontend changes:
- Update validation response types to include structured error object
- Display formatted compatibility errors with human-readable labels
- Hide error details section when no error information available

* test: add comprehensive schema registry compatibility error parser tests

- Document parser behavior with real Confluent/Redpanda response format
- Test handling of unquoted JSON keys in compatibility messages
- Verify regex transformation for invalid JSON structure
- Add edge case coverage for malformed messages

* refactor: improve schema registry compatibility error parser

- Replace string-based JSON fixing with regex approach for better accuracy
- Use regex pattern (\w+): to quote unquoted keys consistently
- Add structured logging for parse failures with original/fixed messages
- Make parseCompatibilityError a Service method for logger access

* test: update integration tests for schema registry compatibility

- Upgrade Redpanda test container from v23.3.18 to v25.2.10
- Add integration test for incompatible protobuf schema changes
- Verify error type and description extraction from compatibility response
- Test field type change detection (string to int32)

* feat(ui): add persistent error banner for schema validation failures

- Add dismissible alert banner that persists validation errors after modal close
- Update openValidationErrorsModal to support onClose callback
- Display error type and description in banner above action buttons
- Auto-clear banner on successful validation or schema creation
- Improve UX by keeping error visible while user fixes schema

Author: c-julin

backend/pkg/api/api_integration_test.go

@@ -62,7 +62,7 @@ func (s *APIIntegrationTestSuite) SetupSuite() {
 	require := require.New(t)
 
 	ctx := context.Background()
-	container, err := redpanda.Run(ctx, "redpandadata/redpanda:v23.3.18")
+	container, err := redpanda.Run(ctx, "redpandadata/redpanda:v25.2.10")
 	require.NoError(err)
 	s.redpandaContainer = container
 

backend/pkg/api/handle_schema_registry_integration_test.go

@@ -123,4 +123,45 @@ func (s *APIIntegrationTestSuite) TestValidateSchema() {
 		assert.False(validationResponse.IsValid)
 		assert.NotEmpty(validationResponse.ParsingError, "parsing error should be set")
 	})
+
+	t.Run("incompatible schema change (protobuf)", func(t *testing.T) {
+		ctx, cancel := context.WithTimeout(t.Context(), 30*time.Second)
+		defer cancel()
+
+		// First, register a schema with string year field
+		originalSchema := "syntax = \"proto3\";\n\npackage test.v1;\n\nmessage Car {\n  string make = 1;\n  string model = 2;\n  string year = 3;\n}\n"
+		registerReq := struct {
+			Schema string `json:"schema"`
+			Type   string `json:"schemaType"`
+		}{
+			Schema: originalSchema,
+			Type:   sr.TypeProtobuf.String(),
+		}
+		registerRes, _ := s.apiRequest(ctx, http.MethodPost, "/api/schema-registry/subjects/test-car-compat/versions", registerReq)
+		require.Equal(200, registerRes.StatusCode)
+
+		// Now try to validate an incompatible change: year field changed from string to int32
+		incompatibleSchema := "syntax = \"proto3\";\n\npackage test.v1;\n\nmessage Car {\n  string make = 1;\n  string model = 2;\n  int32 year = 3;\n}\n"
+		validateReq := struct {
+			Schema string `json:"schema"`
+			Type   string `json:"schemaType"`
+		}{
+			Schema: incompatibleSchema,
+			Type:   sr.TypeProtobuf.String(),
+		}
+		res, body := s.apiRequest(ctx, http.MethodPost, "/api/schema-registry/subjects/test-car-compat/versions/latest/validate", validateReq)
+		require.Equal(200, res.StatusCode)
+
+		validationResponse := console.SchemaRegistrySchemaValidation{}
+		err := json.Unmarshal(body, &validationResponse)
+		require.NoError(err)
+
+		// Schema should parse correctly but fail compatibility check
+		assert.False(validationResponse.IsValid, "schema should be invalid due to compatibility")
+		assert.Empty(validationResponse.ParsingError, "parsing error should not be set for valid protobuf")
+		assert.False(validationResponse.Compatibility.IsCompatible, "schema should not be compatible")
+		assert.NotEmpty(validationResponse.Compatibility.Error.ErrorType, "error type should be set")
+		assert.NotEmpty(validationResponse.Compatibility.Error.Description, "error description should be set")
+		assert.Contains(validationResponse.Compatibility.Error.ErrorType, "FIELD_SCALAR_KIND_CHANGED", "error type should indicate field type change")
+	})
 }

backend/pkg/console/schema_registry.go

@@ -11,10 +11,12 @@ package console
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"log/slog"
 	"net/http"
+	"regexp"
 	"strconv"
 	"strings"
 
@@ -589,8 +591,47 @@ type SchemaRegistrySchemaValidation struct {
 // SchemaRegistrySchemaValidationCompatibility is the response to the compatibility check
 // performed by the schema registry.
 type SchemaRegistrySchemaValidationCompatibility struct {
-	IsCompatible bool   `json:"isCompatible"`
-	Error        string `json:"error,omitempty"`
+	IsCompatible bool                     `json:"isCompatible"`
+	Error        schemaRegValidationError `json:"error,omitempty"`
+}
+
+// schemaRegValidationError represents the structure of compatibility messages from schema registry
+type schemaRegValidationError struct {
+	ErrorType   string `json:"errorType"`
+	Description string `json:"description"`
+}
+
+// parseCompatibilityError parses schema registry messages and returns formatted user-friendly messages.
+// Schema registry may return JSON with unquoted keys that we need to fix before parsing.
+func (s *Service) parseCompatibilityError(messages []string) schemaRegValidationError {
+	if len(messages) == 0 {
+		return schemaRegValidationError{}
+	}
+
+	// Iterate through all messages to extract errorType and description
+	data := schemaRegValidationError{}
+	for _, msg := range messages {
+		// Schema registry may return invalid JSON with unquoted keys like: {errorType:"...", description:"..."}
+		// Use regex to quote unquoted keys: word: becomes "word":
+		fixedMsg := regexp.MustCompile(`(\w+):`).ReplaceAllString(msg, `"$1":`)
+
+		err := json.Unmarshal([]byte(fixedMsg), &data)
+		if err != nil {
+			s.logger.Warn("failed to parse schema registry compatibility error message",
+				slog.String("original_message", msg),
+				slog.String("fixed_message", fixedMsg),
+				slog.String("error", err.Error()))
+			continue
+		}
+
+		// Stop once we have either error type or Description we can exit
+		if data.ErrorType != "" || data.Description != "" {
+			break
+		}
+	}
+
+	// Return empty if we couldn't parse anything useful
+	return data
 }
 
 // ValidateSchemaRegistrySchema validates a given schema by checking:
@@ -608,23 +649,27 @@ func (s *Service) ValidateSchemaRegistrySchema(
 	}
 
 	// Compatibility check from schema registry
-	var compatErr string
+	var compatErr schemaRegValidationError
 	var isCompatible bool
-	compatRes, err := srClient.CheckCompatibility(ctx, subjectName, version, sch)
+	// Use Verbose parameter to get detailed error messages from schema registry
+	compatRes, err := srClient.CheckCompatibility(sr.WithParams(ctx, sr.Verbose), subjectName, version, sch)
 	if err != nil {
-		compatErr = err.Error()
+		compatErr.ErrorType = "Client Error"
+		compatErr.Description = err.Error()
 
 		// If subject doesn't exist, we will reset the error, because new subject schemas
 		// don't have any existing schema and therefore can't be incompatible.
 		var schemaErr *sr.ResponseError
 		if errors.As(err, &schemaErr) {
 			if schemaErr.ErrorCode == 40401 { // Subject not found error code
-				compatErr = ""
+				compatErr = schemaRegValidationError{}
 				isCompatible = true
 			}
 		}
 	} else {
 		isCompatible = compatRes.Is
+		// Parse the messages from schema registry to extract only errorType and description
+		compatErr = s.parseCompatibilityError(compatRes.Messages)
 	}
 
 	var parsingErr string

backend/pkg/console/schema_registry_parser_test.go

@@ -0,0 +1,57 @@
+// Copyright 2025 Redpanda Data, Inc.
+//
+// Use of this software is governed by the Business Source License
+// included in the file https://github.com/redpanda-data/redpanda/blob/dev/licenses/bsl.md
+//
+// As of the Change Date specified in that file, in accordance with
+// the Business Source License, use of this software will be governed
+// by the Apache License, Version 2.0
+
+package console
+
+import (
+	"log/slog"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestParseCompatibilityError demonstrates why the parser exists and how it handles
+// the unusual response format from Confluent Schema Registry.
+//
+// Schema Registry returns compatibility errors with messages that contain invalid JSON:
+// - Keys are unquoted (e.g., {errorType:"..."} instead of {"errorType":"..."})
+// - Multiple messages contain different pieces of information
+// - Some messages contain schema details, versions, and config that need to be skipped
+//
+// Example real response from Confluent and Redpanda Schema Registry:
+//
+//	{
+//	  "is_compatible": false,
+//	  "messages": [
+//	    "{errorType:\"FIELD_SCALAR_KIND_CHANGED\", description:\"The kind of a SCALAR field at path '#/Car/2' in the new schema does not match its kind in the old schema\"}",
+//	    "{oldSchemaVersion: 1}",
+//	    "{oldSchema: 'syntax = \"proto3\";\n\nmessage Car {\n  string make = 1;\n  string model = 2;\n  int32 year = 3;\n}\n'}",
+//	    "{compatibility: 'BACKWARD'}"
+//	  ]
+//	}
+func TestParseCompatibilityError_RealResponse(t *testing.T) {
+	logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelWarn}))
+	s := &Service{logger: logger}
+
+	// This is the actual response format from Confluent and Redpanda Schema Registry
+	// Note: Keys are unquoted, which is invalid JSON
+	messages := []string{
+		`{errorType:"FIELD_SCALAR_KIND_CHANGED", description:"The kind of a SCALAR field at path '#/Car/2' in the new schema does not match its kind in the old schema"}`,
+		`{oldSchemaVersion: 1}`,
+		`{oldSchema: 'syntax = "proto3";\n\nmessage Car {\n  string make = 1;\n  string model = 2;\n  int32 year = 3;\n}\n'}`,
+		`{compatibility: 'BACKWARD'}`,
+	}
+
+	result := s.parseCompatibilityError(messages)
+
+	// The parser should extract the error type and description from the first message
+	assert.Equal(t, "FIELD_SCALAR_KIND_CHANGED", result.ErrorType, "Should extract error type from unquoted JSON")
+	assert.Equal(t, "The kind of a SCALAR field at path '#/Car/2' in the new schema does not match its kind in the old schema", result.Description, "Should extract description")
+}

frontend/src/components/pages/schemas/modals.tsx

@@ -150,12 +150,16 @@ export function openInfoModal(p: {
   });
 }
 
-export function openValidationErrorsModal(result: {
-  isValid: boolean;
-  errorDetails?: string | undefined;
-  isCompatible?: boolean | undefined;
-}) {
-  const { isValid, errorDetails, isCompatible } = result;
+export function openValidationErrorsModal(
+  result: {
+    isValid: boolean;
+    errorDetails?: string | undefined;
+    isCompatible?: boolean | undefined;
+    compatibilityError?: { errorType: string; description: string } | undefined;
+  },
+  onClose?: () => void
+) {
+  const { isValid, errorDetails, isCompatible, compatibilityError } = result;
 
   const compatBox = (() => {
     if (isCompatible === undefined || isValid === false) {
@@ -177,8 +181,28 @@ export function openValidationErrorsModal(result: {
     );
   })();
 
+  const compatErrorBox =
+    compatibilityError && (compatibilityError.errorType || compatibilityError.description) ? (
+      <Box>
+        <Text fontWeight="semibold" mb="2">
+          Compatibility Error Details:
+        </Text>
+        <Box background="gray.100" maxHeight="400px" overflowY="auto" p="6">
+          {compatibilityError.errorType && (
+            <Text color="red.600" fontWeight="bold" mb="2">
+              Error: {compatibilityError.errorType.replace(/_/g, ' ')}
+            </Text>
+          )}
+          {compatibilityError.description && <Text lineHeight="1.6">{compatibilityError.description}</Text>}
+        </Box>
+      </Box>
+    ) : null;
+
   const errDetailsBox = errorDetails ? (
     <Box>
+      <Text fontWeight="semibold" mb="2">
+        Parsing Error:
+      </Text>
       <Box background="gray.100" fontFamily="monospace" letterSpacing="-0.5px" maxHeight="400px" overflowY="auto" p="6">
         {errorDetails?.trim()}
       </Box>
@@ -199,10 +223,12 @@ export function openValidationErrorsModal(result: {
         <Text mb="3">Schema validation failed due to the following error.</Text>
         <Flex direction="column" gap="4">
           {compatBox}
+          {compatErrorBox}
           {errDetailsBox}
         </Flex>
       </>
     ),
+    onClose,
   });
 }