OpenAPITools/openapi-generator · error · RuntimeException

schema format 'event-stream' is required, when SSE is detect

Error message

schema format 'event-stream' is required, when SSE is detected

What it means

Once the generator matches the SSE pattern (a 2xx text/event-stream response whose schema type is array), it requires that array schema to declare format: event-stream (case-insensitive). The templates use this format to emit Flux<EventType> SSE endpoints; without it, generation aborts.

Source

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

                            $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
        }

        // If substituteGenericPagedModel is enabled, replace paged-model return types
        // with org.springframework.data.web.PagedModel<T>.
        if (substituteGenericPagedModel && !pagedModelRegistry.isEmpty()
                && codegenOperation.returnBaseType != null) {

View on GitHub (pinned to fcec517be3)

Solutions

  1. Add format: event-stream to the array schema of the text/event-stream response.
  2. Keep the item type consistent so the subsequent single-item-type check also passes.

Example fix

# before
content:
  text/event-stream:
    schema:
      type: array
      items: { $ref: '#/components/schemas/Event' }

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

Strategy: validation

Validate before calling

// node: every 2xx event-stream array schema must declare format: event-stream
const checkSseFormat = (op) => {
  Object.values(op.responses || {}).forEach(r => {
    const mt = r.content && r.content['text/event-stream'];
    if (mt && mt.schema?.type === 'array' && mt.schema.format !== 'event-stream')
      throw new Error('text/event-stream array schema missing format: event-stream');
  });
};

Try / catch

// Java
try { new DefaultGenerator().opts(input).generate(); }
catch (RuntimeException e) {
    if (e.getMessage().contains("event-stream")) { /* fix spec schema, regenerate once */ }
}

Prevention

When it happens

Trigger: A 2xx response with text/event-stream content whose schema has type: array but no format: event-stream (or a different format).

Common situations: Hand-written SSE specs that stop at type: array; specs generated by tools that drop the format field; teams learning the generator's undocumented SSE convention for the first time.

Related errors

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