tool %q config error: parameter %q (index %d) references '%q

Error message

tool %q config error: parameter %q (index %d) references '%q' in the 'valueFromParam' field, which is not a defined parameter

What it means

A tool parameter uses `valueFromParam` to copy the value of another parameter, but the referenced name is not defined anywhere in the tool's `parameters` list. The parser builds a set of all parameter names first and fails fast on dangling references.

Source

Thrown at internal/server/config.go:515

						validParamNames[pName] = true
					}
				}
			}

			// Validate references
			for i, rawP := range paramsList {
				pMap, ok := rawP.(map[string]any)
				if !ok {
					continue
				}

				pName, _ := pMap["name"].(string)
				refName, _ := pMap["valueFromParam"].(string)

				if refName != "" {
					// Check if the referenced parameter exists
					if !validParamNames[refName] {
						return nil, fmt.Errorf("tool %q config error: parameter %q (index %d) references '%q' in the 'valueFromParam' field, which is not a defined parameter", name, pName, i, refName)
					}

					// Check for self-reference
					if refName == pName {
						return nil, fmt.Errorf("tool %q config error: parameter %q cannot copy value from itself", name, pName)
					}
				}
			}
		}
	}

	dec, err := util.NewStrictDecoder(r)
	if err != nil {
		return nil, fmt.Errorf("error creating decoder: %s", err)
	}
	toolCfg, err := tools.DecodeConfig(ctx, resourceType, name, dec)
	if err != nil {
		if errors.Is(err, tools.ErrUnknownToolType) && util.IgnoreUnknownToolsFromContext(ctx) {

View on GitHub (pinned to 8cc6e09de2)

Solutions

Fix the valueFromParam string to exactly match an existing parameter's name in the same tool
Add the referenced parameter to the parameters list if it should exist
Remove the valueFromParam field if the copy is no longer needed

Example fix

// before
parameters:
  - name: user_id
    type: string
  - name: effective_id
    type: string
    valueFromParam: userId
// after
parameters:
  - name: user_id
    type: string
  - name: effective_id
    type: string
    valueFromParam: user_id

Defensive patterns

Strategy: validation

Validate before calling

func validateParamRefs(params []map[string]any) error {
  names := map[string]bool{}
  for _, p := range params { if n, ok := p["name"].(string); ok { names[n] = true } }
  for _, p := range params {
    if ref, ok := p["valueFromParam"].(string); ok && ref != "" && !names[ref] {
      return fmt.Errorf("valueFromParam %q is not a defined parameter", ref)
    }
  }
  return nil
}

Prevention

Grep valueFromParam references against parameter names whenever renaming parameters
Only reference sibling parameters in the same tool
Add this validation to a pre-commit config linter

When it happens

Trigger: A tools entry has a parameter with `valueFromParam: <name>` where <name> is not any parameter's `name` in the same tool — e.g. a typo, a reference to a parameter that was deleted, or referencing an authClaim/nested field instead of a sibling parameter.

Common situations: Renaming a parameter without updating valueFromParam references; copying parameter blocks between tools; assuming built-in or implicit parameters can be referenced.

Related errors

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