linshenkx/prompt-optimizer · error · RequestConfigError

Image understanding user prompt cannot be empty

Error message

Image understanding user prompt cannot be empty

What it means

Thrown by validateImageUnderstandingRequest when request.userPrompt is not a string or is empty/whitespace-only. The image-understanding endpoints require a textual prompt to accompany the images; an empty prompt is rejected client-side before any API call.

Source

Thrown at packages/core/src/services/llm/adapters/abstract-adapter.ts:208

      }

      if (!['system', 'user', 'assistant', 'tool'].includes(msg.role)) {
        throw new RequestConfigError(`Invalid message role: ${msg.role}`)
      }

      if (typeof msg.content !== 'string') {
        throw new RequestConfigError('Message content must be a string')
      }
    }
  }

  protected validateImageUnderstandingRequest(request: ImageUnderstandingRequest): void {
    if (!request || typeof request !== 'object') {
      throw new RequestConfigError('Image understanding request cannot be empty')
    }

    if (typeof request.userPrompt !== 'string' || !request.userPrompt.trim()) {
      throw new RequestConfigError('Image understanding user prompt cannot be empty')
    }

    if (!Array.isArray(request.images) || request.images.length === 0) {
      throw new RequestConfigError('Image understanding request requires at least one image')
    }

    request.images.forEach((image, index) => {
      if (!image || typeof image !== 'object') {
        throw new RequestConfigError(`Image at index ${index} is invalid`)
      }

      if (typeof image.b64 !== 'string' || !image.b64.trim()) {
        throw new RequestConfigError(`Image at index ${index} is missing base64 data`)
      }
    })
  }

  // ===== 工具方法 =====

View on GitHub (pinned to 3e677b1d9f)

Solutions

1. Default the prompt: request.userPrompt = prompt || 'Describe this image'
2. Require a non-empty prompt in the UI/form layer before invoking the API
3. Trim and check userPrompt.length > 0 in a pre-call validation step

Example fix

// before
await adapter.sendImageUnderstanding({ userPrompt: '', images: [{ b64 }] })

// after
await adapter.sendImageUnderstanding({ userPrompt: 'Describe this image', images: [{ b64 }] })

const prompt = (request.userPrompt ?? '').trim()
if (!prompt) throw new Error('prompt required')
await adapter.sendImageUnderstanding({ ...request, userPrompt: prompt })

function hasValidPrompt(r: ImageUnderstandingRequest): boolean {
  return typeof r.userPrompt === 'string' && r.userPrompt.trim().length > 0
}

null

When it happens

Trigger: Calling sendImageUnderstanding({ userPrompt: '', images: [...] }) or with userPrompt: ' ' or a non-string value (undefined, number).

Common situations: UI prompt field left blank by the user and forwarded unchecked; prompt loaded from config key that doesn't exist (undefined); whitespace from trimmed form input.

Related errors

• Image understanding request cannot be empty
• Image understanding request requires at least one image
• Image at index ${index} is invalid
• Image at index ${index} is missing base64 data
• CONTEXT_ERROR_CODES.STORAGE_ERROR

AI-assisted analysis of linshenkx/prompt-optimizer@3e677b1d9f (2026-08-27). Data as JSON: /api/errors/b65b3852432ed693. Report an issue: GitHub.