{"record":{"id":"838c7b3e0a0780d8","repo":"apache/beam","slug":"model-returned-no-structured-responses","errorCode":null,"errorMessage":"Model returned no structured responses","messagePattern":"Model returned no structured responses","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/ml/inference/openai/src/main/java/org/apache/beam/sdk/ml/inference/openai/OpenAIModelHandler.java","lineNumber":120,"sourceCode":"      StructuredResponseCreateParams<StructuredInputOutput> clientParams =\n          ResponseCreateParams.builder()\n              .model(modelParameters.getModelName())\n              .input(inputBatch)\n              .text(StructuredInputOutput.class, JsonSchemaLocalValidation.NO)\n              .instructions(modelParameters.getInstructionPrompt())\n              .build();\n\n      // Get structured output from the model\n      StructuredInputOutput structuredOutput =\n          client.responses().create(clientParams).output().stream()\n              .flatMap(item -> item.message().stream())\n              .flatMap(message -> message.content().stream())\n              .flatMap(content -> content.outputText().stream())\n              .findFirst()\n              .orElse(null);\n\n      if (structuredOutput == null || structuredOutput.responses == null) {\n        throw new RuntimeException(\"Model returned no structured responses\");\n      }\n\n      // return PredictionResults\n      return structuredOutput.responses.stream()\n          .map(\n              response ->\n                  PredictionResult.create(\n                      OpenAIModelInput.create(response.input),\n                      OpenAIModelResponse.create(response.output)))\n          .collect(Collectors.toList());\n\n    } catch (JsonProcessingException e) {\n      throw new RuntimeException(\"Failed to serialize input batch\", e);\n    }\n  }\n\n  /**\n   * Schema class for structured output response.","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/ml/inference/openai/src/main/java/org/apache/beam/sdk/ml/inference/openai/OpenAIModelHandler.java#L102-L138","documentation":"OpenAIModelHandler.request() parses the model's structured-output response into an OpenAIModelOutput schema object. If the parsed content is null or its responses field is null, there is nothing to map back to inputs, so it throws a RuntimeException with this message rather than returning an empty or null result.","triggerScenarios":"Calling request() when the model response contains no content/output_text parts (refusal, empty completion, content filter), or when the structured output JSON does not match the expected schema so deserialization yields null fields.","commonSituations":"Model refuses the prompt (safety refusal), max output tokens hit so text is truncated away, the response_format/structured-output schema was changed client-side but the prompt does not request it, or a model version returns a different content layout.","solutions":["Ensure the request sets the structured-output response format matching OpenAIModelOutput's schema.","Log the raw response to see refusals, truncation (finish_reason), or content-filter outcomes.","Check finish_reason == 'length' and increase max output tokens if output was cut off.","Handle refusals explicitly: retry with adjusted prompt or emit a fallback OutputT."],"exampleFix":"// before\nChatCompletionCreateParams params = client.chat().completionCreateParams().model(model).addMessage(msg);\n// after\nChatCompletionCreateParams params = client.chat().completionCreateParams().model(model)\n    .responseFormat(ChatCompletionCreateParams.ResponseFormat.JSON_SCHEMA)\n    .addMessage(msg);","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { results = handler.request(batch); } catch (RuntimeException e) { if (e.getMessage().contains(\"no structured responses\")) { /* inspect raw response / retry with adjusted prompt */ } else { throw e; } }","preventionTips":["Always configure strict structured outputs / JSON schema response format","Check finish_reason and refusal fields in raw responses","Set adequate max output tokens","Test prompts against safety refusals"],"tags":["java","openai","structured-output"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}