google-gemini/gemini-cli · error · Error

Template validation failed: Missing required input parameter

Error message

Template validation failed: Missing required input parameters: ${missingKeys.join(', ')}. Available inputs: ${Object.keys(inputs).join(', ')}

What it means

Thrown by templateString() when a template contains ${placeholder} tokens for which no corresponding key exists in the inputs object. The function scans the template with the regex /\$\{(\w+)\}/g, collects all unique placeholder names, and verifies each one is present in the inputs before performing substitution. The error message lists both the missing and available keys for fast diagnosis.

Source

Thrown at packages/core/src/agents/utils.ts:33

 * @throws {Error} if any placeholder key is not found in the inputs.
 */
export function templateString(template: string, inputs: AgentInputs): string {
  const placeholderRegex = /\$\{(\w+)\}/g;

  // First, find all unique keys required by the template.
  const requiredKeys = new Set(
    Array.from(template.matchAll(placeholderRegex), (match) => match[1]),
  );

  // Check if all required keys exist in the inputs.
  const inputKeys = new Set(Object.keys(inputs));
  const missingKeys = Array.from(requiredKeys).filter(
    (key) => !inputKeys.has(key),
  );

  if (missingKeys.length > 0) {
    // Enhanced error message showing both missing and available keys
    throw new Error(
      `Template validation failed: Missing required input parameters: ${missingKeys.join(', ')}. ` +
        `Available inputs: ${Object.keys(inputs).join(', ')}`,
    );
  }

  // Perform the replacement using a replacer function.
  return template.replace(placeholderRegex, (_match, key) =>
    String(inputs[key]),
  );
}

View on GitHub (pinned to 5024443c72)

Solutions

1. Compare the error's 'Missing required input parameters' list against 'Available inputs' and add the missing keys to the inputs object.
2. If a placeholder is optional or may be absent, provide a default: { ...inputs, role: inputs.role ?? 'guest' } before calling templateString.
3. After renaming an input field, grep all templates that reference the old name and update them.
4. Add a unit test that asserts templateString succeeds for the expected input set of each agent definition.

Example fix

// before
const result = templateString('Hello ${name}, role: ${role}', { name: 'Alice' });
// throws: Missing required input parameters: role. Available inputs: name

// after — supply all referenced keys
const result = templateString('Hello ${name}, role: ${role}', {
  name: 'Alice',
  role: 'admin',
});

// Before calling templateString, verify all placeholders are satisfiable
function validateTemplateInputs(template: string, inputs: Record<string, unknown>): string[] {
  const placeholderRegex = /\$\{(\w+)\}/g;
  const required = new Set(
    Array.from(template.matchAll(placeholderRegex), (m) => m[1])
  );
  const available = new Set(Object.keys(inputs));
  return [...required].filter((k) => !available.has(k));
}

const missing = validateTemplateInputs(template, inputs);
if (missing.length > 0) {
  throw new Error(`Missing template inputs: ${missing.join(', ')}`);
}

function isTemplateSatisfiable(
  template: string,
  inputs: AgentInputs
): boolean {
  const placeholderRegex = /\$\{(\w+)\}/g;
  const inputKeys = new Set(Object.keys(inputs));
  for (const match of template.matchAll(placeholderRegex)) {
    if (!inputKeys.has(match[1])) return false;
  }
  return true;
}

try {
  result = templateString(template, inputs);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Template validation failed')) {
    // Provide defaults for missing keys or skip the template
    const enriched = { ...inputs, missingKey: '' };
    result = templateString(template, enriched);
  } else throw e;
}

When it happens

Trigger: Calling templateString(template, inputs) where template references a ${key} that is not a property of inputs. For example, templateString('Hello ${name}, you are ${role}', { name: 'Alice' }) throws because 'role' is missing.

Common situations: Agent input templates in definitions reference variables that the caller didn't supply; refactoring an agent's input schema to rename a field without updating the template (or vice versa); dynamically generated templates where placeholder names don't match runtime input keys; passing a subset of inputs to a template designed for a fuller context.

Related errors

• Missing required variable: ${key}
• PromptConfig must define either `systemPrompt` or `initialMe
• Invalid taskId: ${taskId}
• Security violation: Null byte detected in path.
• Security violation: The path "${trimmedPath}" is outside the

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/efefc55633174ca3. Report an issue: GitHub.