googleapis/mcp-toolbox · error

error substituting params for message: %w

Error message

error substituting params for message: %w

What it means

SubstituteMessages resolves {{.param}} template variables in each prompt message's content using the provided argument values via parameters.ResolveTemplateParams. It wraps and rethrows any per-message template resolution failure, attributing it to the specific message being substituted.

Source

Thrown at internal/prompts/messages.go:67

	}
	return nil
}

// SubstituteMessages takes a slice of Messages and a set of parameter values,
// and returns a new slice with all template variables resolved.
func SubstituteMessages(messages []Message, arguments Arguments, argValues parameters.ParamValues) ([]Message, error) {
	substitutedMessages := make([]Message, 0, len(messages))
	argsMap := argValues.AsMap()

	var params parameters.Parameters
	for _, arg := range arguments {
		params = append(params, arg.Parameter)
	}

	for _, msg := range messages {
		substitutedContent, err := parameters.ResolveTemplateParams(params, msg.Content, argsMap)
		if err != nil {
			return nil, fmt.Errorf("error substituting params for message: %w", err)
		}

		substitutedMessages = append(substitutedMessages, Message{
			Role:    msg.Role,
			Content: substitutedContent,
		})
	}

	return substitutedMessages, nil
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Read the wrapped %w error to find the offending variable/syntax, then fix that message's content template.
2. Ensure every {{.x}} in message content has a matching entry in the prompt's `arguments:` list and that the caller supplies its value.
3. Fix Go template syntax: use {{.paramName}} with matching braces and no unsupported expressions.
4. Test the prompt locally with all parameters filled before deploying the config.

Example fix

// before
content: "List tables in {{.databse}}"
// after
content: "List tables in {{.database}}"

// Pre-check: every {{.var}} in message content has a declared argument
for _, msg := range cfg.Messages {
	for _, v := range extractTemplateVars(msg.Content) {
		if !declaredArgs[v] {
			return fmt.Errorf("message references undeclared parameter %q", v)
		}
	}
}

sub, err := prompts.SubstituteParams(prompt, args)
if err != nil {
	if strings.Contains(err.Error(), "error substituting params for message") {
		return fmt.Errorf("check that all {{.param}} in prompt content match declared arguments and are supplied: %w", err)
	}
	return err
}

When it happens

Trigger: A message content references a template variable that has no corresponding parameter definition (missing from argsMap), or the template syntax is malformed (e.g. `{{.name` unclosed, or invalid Go template expression) — ResolveTemplateParams errors for each message in turn.

Common situations: Renaming an argument in the `arguments:` list but not in message content; typo in the template variable ({{.userNam}}); using unsupported template constructs like pipelines or functions the resolver rejects; a caller invokes a prompt without supplying all declared parameters and the resolver requires them.

Related errors

• error parsing argument: %w
• invalid role %q: must be 'user' or 'assistant'
• `introspectionEndpoint` is not allowed when `mcpEnabled` is
• `introspectionMethod` is not allowed when `mcpEnabled` is fa
• `introspectionParamName` is not allowed when `mcpEnabled` is

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/688ebc3e5c700afb. Report an issue: GitHub.