googleapis/mcp-toolbox · error

params must be a valid JSON string: %w

Error message

params must be a valid JSON string: %w

What it means

Thrown by runInvoke (cmd/internal/invoke/command.go:111) when the optional second CLI argument (the tool params string) is non-empty but fails util.DecodeJSON into map[string]any. The invoke command requires params to be a single, well-formed JSON object literal so they can be matched against the tool's parameter schema. This is a user-input validation error, not a library fault.

Source

Thrown at cmd/internal/invoke/command.go:111

			return errMsg
		}
	}

	err = tool.ValidateSource(src)
	if err != nil {
		opts.Logger.ErrorContext(ctx, err.Error())
		return err
	}

	var paramsInput string
	if len(args) > 1 {
		paramsInput = args[1]
	}

	params := make(map[string]any)
	if paramsInput != "" {
		if err := util.DecodeJSON(strings.NewReader(paramsInput), &params); err != nil {
			errMsg := fmt.Errorf("params must be a valid JSON string: %w", err)
			opts.Logger.ErrorContext(ctx, errMsg.Error())
			return errMsg
		}
	}

	toolParams, err := tool.GetParameters(src)
	if err != nil {
		errMsg := fmt.Errorf("error getting parameters for tool: %w", err)
		opts.Logger.ErrorContext(ctx, errMsg.Error())
		return errMsg
	}

	parsedParams, err := parameters.ParseParams(toolParams, params, nil)
	if err != nil {
		errMsg := fmt.Errorf("invalid parameters: %w", err)
		opts.Logger.ErrorContext(ctx, errMsg.Error())
		return errMsg
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Wrap the params argument in single quotes so the shell does not alter it: toolbox invoke my-tool '{"name": "value"}'.
2. Validate the JSON with `echo '<params>' | jq .` before invoking to see the exact syntax error.
3. Pass an empty string or omit the argument entirely if the tool takes no parameters.
4. Write complex params to a file and pass its contents: toolbox invoke my-tool "$(cat params.json)".

Example fix

// before (shell eats quotes -> invalid JSON)
toolbox invoke execute_sql {"sql": "SELECT 1"}
// after
toolbox invoke execute_sql '{"sql": "SELECT 1"}'

params='{"sql": "SELECT 1"}'
echo "$params" | jq -e type >/dev/null || { echo 'params is not valid JSON'; exit 1; }

if err := runInvoke(...); err != nil {
  if strings.Contains(err.Error(), "params must be a valid JSON string") {
    // re-prompt for params or show usage
  }
}

When it happens

Trigger: Running `toolbox invoke <tool> '<params>'` where the second arg is malformed JSON: unquoted shell-expanded braces, single quotes inside JSON, trailing commas, unquoted keys, non-object JSON like a bare string, or shell mangling of double quotes.

Common situations: Quoting mistakes on the command line (shell strips or splits the JSON), copy-pasting params with smart quotes, forgetting to single-quote the JSON so the shell word-splits it, or passing a JSON array instead of an object.

Related errors

• failed to marshal result: %w
• failed to initialize resources: %w
• tool %q not found
• unable to retrieve source for tool %s
• error getting parameters for tool: %w

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