googleapis/mcp-toolbox · error

%d is under the minimum value

Error message

%d is under the minimum value

What it means

IntParameter.Parse rejects an integer because it is below the parameter's configured minValue. The value parsed as a valid int but fails the range check enforced by tool authors to keep queries safe (e.g. positive limits, non-negative offsets). This is expected input validation from the toolbox.

Source

Thrown at internal/util/parameters/parameters.go:824

	case int32:
		out = int(newV)
	case int64:
		out = int(newV)
	case json.Number:
		newI, err := newV.Int64()
		if err != nil {
			return nil, &ParseTypeError{p.Name, p.Type, v}
		}
		out = int(newI)
	}
	if !p.IsAllowedValues(out) {
		return nil, fmt.Errorf("%d is not an allowed value", out)
	}
	if p.IsExcludedValues(out) {
		return nil, fmt.Errorf("%d is an excluded value", out)
	}
	if p.MinValue != nil && out < *p.MinValue {
		return nil, fmt.Errorf("%d is under the minimum value", out)
	}
	if p.MaxValue != nil && out > *p.MaxValue {
		return nil, fmt.Errorf("%d is above the maximum value", out)
	}
	return out, nil
}

func (p *IntParameter) GetAuthServices() []ParamAuthService {
	return p.AuthServices
}

func (p *IntParameter) GetDefault() any {
	if p.Default == nil {
		return nil
	}
	return *p.Default
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Resend the request with an integer >= the configured minValue (check the tool's parameter manifest/description)
2. Clamp values on the client side before calling, e.g. max(minValue, value)
3. If smaller values are legitimately useful, lower or remove minValue in tools.yaml (or WithIntMinValue) and redeploy

Example fix

// before
params := map[string]any{"limit": 0} // minValue is 1
// after
params := map[string]any{"limit": 1}

func validateMinInt(v int, minValue int) error {
    if v < minValue {
        return fmt.Errorf("%d is below minimum %d", v, minValue)
    }
    return nil
}
// usage: validateMinInt(limit, 1)

func withinMinInt(v, minValue int) bool { return v >= minValue }

out, err := tool.Parse(params)
if err != nil && strings.Contains(err.Error(), "is under the minimum value") {
    // clamp: params["limit"] = minValue from manifest and retry once
}

When it happens

Trigger: Invoking a tool with an integer smaller than minValue configured via yaml 'minValue:' or WithIntMinValue. Example: minValue 1 and the request passes 0 or -5.

Common situations: LLMs choosing limit=0 or negative offsets; pagination code underflowing (page 0 -> offset -10); clients written before a minValue was added to the tool config; user-supplied numbers passed through unclamped.

Related errors

• %d is above the maximum value
• %g is under the minimum value
• %g is above the maximum value
• unable to process parameters: %w
• %d is not an allowed value

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