{"record":{"id":"8aebcf2a39a44d64","repo":"linshenkx/prompt-optimizer","slug":"iteration-requires-advanced-template-message-arra","errorCode":null,"errorMessage":"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","messagePattern":"Iteration requires advanced template \\(message array format\\) for variable substitution\\.\\\\nTemplate ID: (.+?)\\\\nCurrent template type: Simple template \\(string format\\)\\\\nSuggestion: Please use message array format template that supports (.+?)\\} and (.+?)\\} variables","errorType":"exception","errorClass":"IterationError","httpStatus":null,"severity":"error","filePath":"packages/core/src/services/prompt/service.ts","lineNumber":325,"sourceCode":"          error instanceof Error ? error.message : String(error);\n        throw new IterationError(\n          originalPrompt,\n          iterateInput,\n          `Iteration failed: ${errorMessage}`,\n        );\n      }\n\n      if (!template?.content) {\n        throw new IterationError(\n          originalPrompt,\n          iterateInput,\n          \"Iteration failed: Template not found or invalid\",\n        );\n      }\n\n      // 🔧 迭代功能必须使用高级模板（message array 格式）以支持变量替换\n      if (typeof template.content === \"string\") {\n        throw new IterationError(\n          originalPrompt,\n          iterateInput,\n          `Iteration requires advanced template (message array format) for variable substitution.\\n` +\n            `Template ID: ${template.id}\\n` +\n            `Current template type: Simple template (string format)\\n` +\n            `Suggestion: Please use message array format template that supports {{lastOptimizedPrompt}} and {{iterateInput}} variables`,\n        );\n      }\n\n      // 使用TemplateProcessor处理模板和变量替换\n      const context: TemplateContext = {\n        originalPrompt,\n        lastOptimizedPrompt,\n        iterateInput,\n        customVariables: contextData?.variables,\n        tools: contextData?.tools,\n      };\n","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/linshenkx/prompt-optimizer/blob/3e677b1d9f7e0493c142c175560531e7ae786dce/packages/core/src/services/prompt/service.ts#L307-L343","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use or create an advanced (message array) template for iteration — content must be an array of message objects","Ensure the array's text includes {{lastOptimizedPrompt}} and {{iterateInput}} placeholders","If a custom templateId is passed from UI state, switch it to a template built for iteration (e.g. DEFAULT_TEMPLATES.ITERATE)","Update any code that writes string content into templates intended for iteratePrompt"],"exampleFix":"// before (simple string template — throws)\nawait templateManager.createTemplate({ id: \"iter\", content: \"Improve: {{prompt}}\" });\nawait promptService.iteratePrompt(lastPrompt, input, modelKey, \"iter\");\n\n// after (advanced message-array template)\nawait templateManager.createTemplate({\n  id: \"iter\",\n  content: [\n    { role: \"system\", content: \"You refine prompts.\" },\n    { role: \"user\", content: \"Previous result:\\n{{lastOptimizedPrompt}}\\n\\nChange request:\\n{{iterateInput}}\" },\n  ],\n});\nawait promptService.iteratePrompt(lastPrompt, input, modelKey, \"iter\");","handlingStrategy":"type-guard","validationCode":"const tpl = await templateManager.getTemplate(templateId || DEFAULT_TEMPLATES.ITERATE);\nif (typeof tpl?.content === \"string\") {\n  throw new Error(\"Iteration needs a message-array template; convert it first.\");\n}","typeGuard":"const isAdvancedTemplate = (t: { content: unknown }): t is { content: Array<{ role: string; content: string }> } =>\n  Array.isArray(t.content) && t.content.every(m => typeof m?.role === \"string\");","tryCatchPattern":"try {\n  await promptService.iteratePrompt(last, input, modelKey, templateId);\n} catch (e) {\n  if (e instanceof IterationError && /advanced template/.test(e.message)) {\n    templateId = DEFAULT_TEMPLATES.ITERATE; // use a known message-array template\n    await promptService.iteratePrompt(last, input, modelKey, templateId);\n  } else throw e;\n}","preventionTips":["Author iterate templates as message arrays containing {{lastOptimizedPrompt}} and {{iterateInput}}","Guard template format before calling iterate(Prompt|PromptStream)","Restrict the iteration template picker in the UI to advanced templates"],"tags":["template-format","iteration","variable-substitution","message-array"],"backgroundTag":"template-format-mismatch","analyzedSha":"3e677b1d9f7e0493c142c175560531e7ae786dce","analyzedAt":"2026-08-27T21:29:16.709Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}