What causes "only single item type is supported, when SSE is detected" in OpenAPITools/openapi-generator?

Point every text/event-stream array at the same item $ref or primitive type.

OpenAPITools/openapi-generator · error · RuntimeException

only single item type is supported, when SSE is detected

Error message

only single item type is supported, when SSE is detected

What it means

For an operation recognised as SSE, the generator collects the item types (the type or $ref of items) of every text/event-stream array schema across 2xx responses. A reactive stream endpoint can emit only one element type (Flux<T>), so more than one distinct item type aborts generation.

Source

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

            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
        }

        // If substituteGenericPagedModel is enabled, replace paged-model return types
        // with org.springframework.data.web.PagedModel<T>.
        if (substituteGenericPagedModel && !pagedModelRegistry.isEmpty()
                && codegenOperation.returnBaseType != null) {
            PagedModelScanUtils.DetectedPagedModel detected =
                    pagedModelRegistry.get(codegenOperation.returnBaseType);
            if (detected != null) {
                String oldType = codegenOperation.returnType;
                // Run through toModelName so that schemaMappings (e.g. User → com.example.MyUser)
                // are honored: the mapped name is used both in the type arg and for import resolution.
                String itemType = toModelName(detected.itemSchemaName);
                codegenOperation.returnType = pagedModelClassName + "<" + itemType + ">";
                codegenOperation.returnBaseType = pagedModelClassName;

View on GitHub (pinned to fcec517be3)

Solutions

Point every text/event-stream array at the same item $ref or primitive type.
If different event shapes must be streamed, define one envelope schema with oneOf/anyOf variants as the single item type.

Example fix

# before
'200':
  content:
    text/event-stream:
      schema: { type: array, format: event-stream, items: { $ref: '#/components/schemas/Cat' } }
'201':
  content:
    text/event-stream:
      schema: { type: array, format: event-stream, items: { $ref: '#/components/schemas/Dog' } }

# after
components:
  schemas:
    PetEvent:
      oneOf: [ { $ref: '#/components/schemas/Cat' }, { $ref: '#/components/schemas/Dog' } ]
'200':
  content:
    text/event-stream:
      schema: { type: array, format: event-stream, items: { $ref: '#/components/schemas/PetEvent' } }

Defensive patterns

Strategy: validation

Validate before calling

// node: all event-stream arrays in an operation must share one item type
const checkSseItems = (op) => {
  const items = Object.values(op.responses || {})
    .map(r => r.content?.['text/event-stream']?.schema)
    .filter(s => s?.type === 'array')
    .map(s => s.items?.$ref ?? s.items?.type);
  if (new Set(items).size > 1) throw new Error(`multiple SSE item types: ${items.join(',')}`);
};

Try / catch

// Java
try { new DefaultGenerator().opts(input).generate(); }
catch (RuntimeException e) {
    // unify item schemas (oneOf envelope) in the spec, then regenerate
}

Prevention

Model heterogeneous events as one envelope schema with oneOf variants.
Lint for a single item $ref per SSE operation.
Version event schemas centrally so renamed $refs propagate to all responses.

When it happens

Trigger: Two 2xx event-stream responses whose arrays hold different item schemas (e.g. items: $ref Cat on one, items: $ref Dog on the other), or one array of primitives and one array of objects.

Common situations: Streaming APIs that send different event payloads for different success codes; specs where one event type was renamed in a $ref but not everywhere; merging specs that each defined their own event schema.

Related errors

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