OpenAPITools/openapi-generator · error · RuntimeException

only 1 response media type supported, when SSE is detected

Error message

only 1 response media type supported, when SSE is detected

What it means

While post-processing an operation, the Spring generator detects the server-sent-events (SSE) pattern: a 2xx response with media type text/event-stream whose schema has type array. It then groups all text/event-stream success schemas by type and requires exactly one distinct type; if both array and a non-array type appear, generation aborts because a reactive SSE endpoint can only be modelled one way.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java:1511

                        schema:
                        type: array
                        format: event-stream
                        items:
                            type: <type> or
                            $ref: <typeRef>
                 */
            Map<String, List<Schema>> schemaTypes = operation.getResponses().entrySet().stream()
                    .map(e -> Pair.of(e.getValue(), fromResponse(e.getKey(), e.getValue())))
                    .filter(p -> p.getRight().is2xx) // consider only success
                    .map(p -> p.getLeft().getContent().get(MEDIA_EVENT_STREAM))
                    .map(MediaType::getSchema)
                    .collect(Collectors.toList()).stream()
                    .collect(Collectors.groupingBy(Schema::getType));
            if (schemaTypes.containsKey("array")) {
                // we have a match with SSE pattern
                // double check potential conflicting, multiple specs
                if (schemaTypes.size() > 1) {
                    throw new RuntimeException("only 1 response media type supported, when SSE is detected");
                }
                // double check schema format
                List<Schema> eventTypes = schemaTypes.get("array");
                if (eventTypes.stream().anyMatch(schema -> !"event-stream".equalsIgnoreCase(schema.getFormat()))) {
                    throw new RuntimeException("schema format 'event-stream' is required, when SSE is detected");
                }
                // double check item types
                Set<String> itemTypes = eventTypes.stream()
                        .map(schema -> schema.getItems().getType() != null
                                ? schema.getItems().getType()
                                : schema.getItems().get$ref())
                        .collect(Collectors.toSet());
                if (itemTypes.size() > 1) {
                    throw new RuntimeException("only single item type is supported, when SSE is detected");
                }
                codegenOperation.vendorExtensions.put("x-sse", true);
            } // Not an SSE compliant definition
        }

View on GitHub (pinned to fcec517be3)

Solutions

  1. Keep a single schema type across all 2xx text/event-stream responses: move non-stream success payloads to application/json or another media type.
  2. Verify the array schema also declares format: event-stream and one item type, so the follow-up SSE checks pass.
  3. Model varied payloads as a oneOf item schema inside the single event-stream array.

Example fix

# before
responses:
  '200':
    content:
      text/event-stream:
        schema:
          type: array
          format: event-stream
          items: { $ref: '#/components/schemas/Event' }
  '201':
    content:
      text/event-stream:
        schema:
          type: object   # second schema type -> error

# after
responses:
  '200':
    content:
      text/event-stream:
        schema:
          type: array
          format: event-stream
          items: { $ref: '#/components/schemas/Event' }
Defensive patterns

Strategy: validation

Validate before calling

// node: reject mixed schema types across 2xx event-stream responses
const assertSingleSseType = (op) => {
  const types = Object.values(op.responses || {})
    .filter(r => r.content && r.content['text/event-stream'])
    .map(r => r.content['text/event-stream'].schema?.type);
  const uniq = [...new Set(types)];
  if (uniq.length > 1) throw new Error(`multiple SSE schema types: ${uniq.join(',')}`);
};
Object.values(spec.paths).forEach(p => Object.values(p).forEach(assertSingleSseType));

Try / catch

// Java: catch spec-shape errors separately from option errors
try { new DefaultGenerator().opts(input).generate(); }
catch (RuntimeException e) {
    // SSE messages come from operation post-processing; point users at the operation in the spec
    throw new SpecValidationException(e.getMessage(), e);
}

Prevention

When it happens

Trigger: An operation declares multiple 2xx responses (e.g. 200 and 201) with text/event-stream content, where one response schema has type: array and another has type: object or type: string.

Common situations: Async APIs that mix event streams and plain JSON success bodies under different status codes; specs assembled from multiple teams; specs converted from other formats where media types got merged onto several success responses.

Related errors

AI-assisted analysis of OpenAPITools/openapi-generator@fcec517be3 (2026-08-22). Data as JSON: /api/errors/95eb4273250418a5. Report an issue: GitHub.