spring-projects/spring-ai · error · IllegalArgumentException

Image prompt instructions cannot be empty

Error message

Image prompt instructions cannot be empty

What it means

OpenAiImageOptions.toOpenAiImageGenerateParams requires the ImagePrompt to contain at least one instruction/message; an empty instructions list is rejected with this IllegalArgumentException before any API call is made.

Source

Thrown at models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiImageOptions.java:180

		if (o == null || getClass() != o.getClass()) {
			return false;
		}
		OpenAiImageOptions that = (OpenAiImageOptions) o;
		return Objects.equals(this.n, that.n) && Objects.equals(this.width, that.width)
				&& Objects.equals(this.height, that.height) && Objects.equals(this.quality, that.quality)
				&& Objects.equals(this.responseFormat, that.responseFormat) && Objects.equals(this.size, that.size)
				&& Objects.equals(this.style, that.style) && Objects.equals(this.user, that.user);
	}

	@Override
	public int hashCode() {
		return Objects.hash(this.n, this.width, this.height, this.quality, this.responseFormat, this.size, this.style,
				this.user);
	}

	public ImageGenerateParams toOpenAiImageGenerateParams(ImagePrompt imagePrompt) {
		if (imagePrompt.getInstructions().isEmpty()) {
			throw new IllegalArgumentException("Image prompt instructions cannot be empty");
		}

		String prompt = imagePrompt.getInstructions().get(0).getText();
		ImageGenerateParams.Builder builder = ImageGenerateParams.builder().prompt(prompt);

		// Use deployment name if available (for Microsoft Foundry), otherwise use model
		// name
		if (this.getDeploymentName() != null) {
			builder.model(this.getDeploymentName());
		}
		else if (this.getModel() != null) {
			builder.model(this.getModel());
		}

		if (this.getN() != null) {
			builder.n(this.getN().longValue());
		}
		if (this.getQuality() != null) {

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Validate the prompt text is non-blank before calling the model and return a validation error to the caller.
2. Ensure you construct the ImagePrompt with at least one UserMessage containing text.
3. Trim and check user input; reject empty prompts upstream of the model call.

Example fix

// before
imageModel.call(new ImagePrompt(List.of()));
// after
if (prompt == null || prompt.isBlank()) {
    throw new IllegalArgumentException("Image prompt text must not be empty");
}
imageModel.call(new ImagePrompt(prompt));

if (imagePrompt == null || imagePrompt.getInstructions() == null || imagePrompt.getInstructions().isEmpty()) {
    throw new IllegalArgumentException("ImagePrompt must contain at least one instruction");
}

try {
    return imageModel.call(imagePrompt);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("instructions cannot be empty")) {
        throw new EmptyPromptException("Provide non-empty prompt text", e);
    }
    throw e;
}

When it happens

Trigger: Calling imageModel.call(new ImagePrompt(List.of())) or building an ImagePrompt with no text messages, so imagePrompt.getInstructions().isEmpty() is true at OpenAiImageOptions.java:180.

Common situations: Programmatically assembling prompts from user input that arrives empty, filtering out blank messages before building the prompt, or forgetting to add any Message to the prompt list.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• ImagePrompt must contain at least one non-empty message
• No embedding input is provided - all texts are null or empty
• SSE connection '<connectionName>' requires a 'url' property.
• Method must not be null
• Method must have exactly 1 parameter (List<McpSchema.Prompt>

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/2f604e9d6c0b76a5. Report an issue: GitHub.