linshenkx/prompt-optimizer · error · IterationError

Iteration failed: Template not found or invalid

Error message

Iteration failed: Template not found or invalid

What it means

Thrown when the iteration template was fetched successfully but has no content (template?.content is null/undefined/empty). An iteration cannot proceed without template content to render, so the service aborts with IterationError 'Template not found or invalid'.

Source

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

      // 获取迭代提示词
      let template;
      try {
        template = await this.templateManager.getTemplate(
          templateId || DEFAULT_TEMPLATES.ITERATE,
        );
      } catch (error) {
        const errorMessage =
          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`,
        );
      }

View on GitHub (pinned to 3e677b1d9f)

Solutions

1. Load the template and check its content field: templateManager.getTemplate(templateId || DEFAULT_TEMPLATES.ITERATE)
2. Edit/re-save the template so content is a non-empty message array
3. If the default template is broken, re-seed built-in templates
4. Validate imported templates for a non-empty content array before registering them

Example fix

// before
await promptService.iteratePrompt(lastPrompt, input, modelKey, "broken-tpl");

// after
const tpl = await templateManager.getTemplate("broken-tpl");
if (!tpl?.content || (Array.isArray(tpl.content) && tpl.content.length === 0)) {
  await templateManager.updateTemplate("broken-tpl", { content: validMessageArray });
}
await promptService.iteratePrompt(lastPrompt, input, modelKey, "broken-tpl");

const tpl = await templateManager.getTemplate(templateId || DEFAULT_TEMPLATES.ITERATE);
const hasContent = !!tpl?.content && (!Array.isArray(tpl.content) || tpl.content.length > 0);
if (!hasContent) throw new Error("Iteration template has no content");

const hasTemplateContent = (t?: { content?: unknown }): boolean =>
  !!t?.content && (!Array.isArray(t.content) || (t.content as unknown[]).length > 0);

try {
  await promptService.iteratePrompt(last, input, modelKey, templateId);
} catch (e) {
  if (e instanceof IterationError && /Template not found or invalid/.test(e.message)) {
    await repairOrReseedTemplate(templateId);
  } else throw e;
}

When it happens

Trigger: An iterate template registered with empty content, a template record whose content field failed to serialize/persist, or a template object shape that doesn't match the expected Template type (content missing rather than empty string).

Common situations: Manually created templates saved without content; partial writes to the template store (crash during save); importing templates from another version where the content field was renamed.

Related errors

• Unrecognized data structure
• ${label} content must not be empty.
• Iteration failed: ${errorMessage}
• No valid messages after processing
• Template must be a non-empty string

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