linshenkx/prompt-optimizer · error · IterationError

Iteration requires advanced template (message array format)

Error message

Iteration requires advanced template (message array format) for variable substitution.\nTemplate ID: ${template.id}\nCurrent template type: Simple template (string format)\nSuggestion: Please use message array format template that supports {{lastOptimizedPrompt}} and {{iterateInput}} variables

What it means

iteratePrompt performs variable substitution ({{lastOptimizedPrompt}}, {{iterateInput}}) which only works on advanced templates whose content is a message array. If the resolved template's content is a plain string (simple template), the service throws IterationError explaining that iteration requires the message-array format. This is a format/compatibility constraint, not a missing template.

Source

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

          error instanceof Error ? error.message : String(error);
        throw new IterationError(
          originalPrompt,
          iterateInput,
          `Iteration failed: ${errorMessage}`,
        );
      }

      if (!template?.content) {
        throw new IterationError(
          originalPrompt,
          iterateInput,
          "Iteration failed: Template not found or invalid",
        );
      }

      // 🔧 迭代功能必须使用高级模板（message array 格式）以支持变量替换
      if (typeof template.content === "string") {
        throw new IterationError(
          originalPrompt,
          iterateInput,
          `Iteration requires advanced template (message array format) for variable substitution.\n` +
            `Template ID: ${template.id}\n` +
            `Current template type: Simple template (string format)\n` +
            `Suggestion: Please use message array format template that supports {{lastOptimizedPrompt}} and {{iterateInput}} variables`,
        );
      }

      // 使用TemplateProcessor处理模板和变量替换
      const context: TemplateContext = {
        originalPrompt,
        lastOptimizedPrompt,
        iterateInput,
        customVariables: contextData?.variables,
        tools: contextData?.tools,
      };

View on GitHub (pinned to 3e677b1d9f)

Solutions

1. Use or create an advanced (message array) template for iteration — content must be an array of message objects
2. Ensure the array's text includes {{lastOptimizedPrompt}} and {{iterateInput}} placeholders
3. If a custom templateId is passed from UI state, switch it to a template built for iteration (e.g. DEFAULT_TEMPLATES.ITERATE)
4. Update any code that writes string content into templates intended for iteratePrompt

Example fix

// before (simple string template — throws)
await templateManager.createTemplate({ id: "iter", content: "Improve: {{prompt}}" });
await promptService.iteratePrompt(lastPrompt, input, modelKey, "iter");

// after (advanced message-array template)
await templateManager.createTemplate({
  id: "iter",
  content: [
    { role: "system", content: "You refine prompts." },
    { role: "user", content: "Previous result:\n{{lastOptimizedPrompt}}\n\nChange request:\n{{iterateInput}}" },
  ],
});
await promptService.iteratePrompt(lastPrompt, input, modelKey, "iter");

const tpl = await templateManager.getTemplate(templateId || DEFAULT_TEMPLATES.ITERATE);
if (typeof tpl?.content === "string") {
  throw new Error("Iteration needs a message-array template; convert it first.");
}

const isAdvancedTemplate = (t: { content: unknown }): t is { content: Array<{ role: string; content: string }> } =>
  Array.isArray(t.content) && t.content.every(m => typeof m?.role === "string");

try {
  await promptService.iteratePrompt(last, input, modelKey, templateId);
} catch (e) {
  if (e instanceof IterationError && /advanced template/.test(e.message)) {
    templateId = DEFAULT_TEMPLATES.ITERATE; // use a known message-array template
    await promptService.iteratePrompt(last, input, modelKey, templateId);
  } else throw e;
}

When it happens

Trigger: Passing a templateId whose template.content is a string (simple format) to iteratePrompt; using the default ITERATE template after it was overwritten with a simple string template; upgrading from a version where iterate templates were string-based.

Common situations: Users creating a custom iterate template as a plain string; reusing an optimize-style string template for iteration; version migrations that changed the expected template format.

Related errors

• Iteration failed: ${errorMessage}
• Iteration failed: Template not found or invalid

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