linshenkx/prompt-optimizer · error · ServiceDependencyError

Image understanding service is not initialized

Error message

Image understanding service is not initialized

What it means

The prompt service needs an injected IImageUnderstandingService for image/vision workflows; requireImageUnderstandingService throws ServiceDependencyError when it was never initialized. Any path that touches image understanding (optimization with inputImages, testPromptStream with images) goes through this guard.

Source

Thrown at packages/core/src/services/prompt/service.ts:887

    message = message.replace(
      /data:image\/[a-z0-9.+-]+;base64,[a-z0-9+/=]+/gi,
      "[redacted-image]",
    );

    for (const image of inputImages) {
      const rawB64 = image.b64.trim();
      if (rawB64 && message.includes(rawB64)) {
        message = message.split(rawB64).join("[redacted-image]");
      }
    }

    return message;
  }

  private requireImageUnderstandingService(): IImageUnderstandingService {
    if (!this.imageUnderstandingService) {
      throw new ServiceDependencyError(
        "ImageUnderstandingService",
        "Image understanding service is not initialized",
      );
    }
    return this.imageUnderstandingService;
  }

  private buildInputImagesManifest(request: OptimizationRequest): string {
    if (!this.hasInputImages(request)) {
      return "[]";
    }

    return JSON.stringify(
      request.inputImages.map((image, index) => ({
        index: index + 1,
        label: `Image ${index + 1}`,
        mimeType: image.mimeType || "image/png",
      })),

View on GitHub (pinned to 3e677b1d9f)

Solutions

1. Initialize/register the image understanding service on PromptService before making image calls
2. If running a custom DI setup, verify the IImageUnderstandingService binding exists and is resolved
3. Gate image features in your UI until the service is confirmed available

Example fix

// before
const svc = new PromptService({ modelManager, templateManager });
await svc.optimizePrompt({ targetPrompt, modelKey, inputImages: [blob] });

// after
const svc = new PromptService({ modelManager, templateManager, imageUnderstandingService });
await svc.optimizePrompt({ targetPrompt, modelKey, inputImages: [blob] });

if (!('imageUnderstandingService' in svc) || !svc.imageUnderstandingService) {
  // skip image features or initialize service first
}

const canProcessImages = (svc: PromptService): boolean =>
  svc.imageUnderstandingService != null;

try {
  await svc.optimizePrompt({ ...req, inputImages });
} catch (e) {
  if (e instanceof ServiceDependencyError && e.service === 'ImageUnderstandingService') {
    // hide image upload UI / initialize the service
  } else throw e;
}

When it happens

Trigger: Calling optimizePrompt/optimizePromptStream with inputImages, or testPromptStream with image content, when the PromptService was constructed without calling the image understanding service initializer/setter.

Common situations: DI container wiring forgot to register the image service; running in a minimal/embedded environment where vision support is intentionally not bundled; upgrading to a version where the service must be registered explicitly.

Related errors

• Image understanding service is not available for multimodal
• Image storage service is required to resolve evaluation imag
• [BasicSystemSession] ImageStorageService is unavailable; can
• [ImageImage2ImageSession] PreferenceService is unavailable;
• [ImageImage2ImageSession] ImageStorageService is unavailable

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