What causes "Expected integer, got {raw!r}" in PrefectHQ/fastmcp?

Pass a valid integer string (e.g. 42, -7) for integer-typed arguments

PrefectHQ/fastmcp · error · ValueError

Expected integer, got {raw!r}

Error message

Expected integer, got {raw!r}

What it means

coerce_value converts CLI/elicitation string input into JSON-schema-typed values for the fastmcp client tool calls. When the schema declares type integer and Python's int() cannot parse the raw string, it raises ValueError naming the offending raw value. Note int() accepts float-like strings ('3.0') but not arbitrary text.

Source

Thrown at fastmcp_slim/fastmcp/cli/client.py:273

        elicitation_handler=_terminal_elicitation_handler,
    )


# ---------------------------------------------------------------------------
# Argument coercion
# ---------------------------------------------------------------------------


def coerce_value(raw: str, schema: dict[str, Any]) -> Any:
    """Coerce a string CLI value according to a JSON-Schema type hint."""

    schema_type = schema.get("type", "string")

    if schema_type == "integer":
        try:
            return int(raw)
        except ValueError:
            raise ValueError(f"Expected integer, got {raw!r}") from None

    if schema_type == "number":
        try:
            return float(raw)
        except ValueError:
            raise ValueError(f"Expected number, got {raw!r}") from None

    if schema_type == "boolean":
        if raw.lower() in ("true", "1", "yes"):
            return True
        if raw.lower() in ("false", "0", "no"):
            return False
        raise ValueError(f"Expected boolean, got {raw!r}")

    if schema_type in ("array", "object"):
        try:
            return json.loads(raw)
        except json.JSONDecodeError:

View on GitHub (pinned to 1f02114297)

Solutions

Pass a valid integer string (e.g. 42, -7) for integer-typed arguments
Quote and verify values in shell invocations of the CLI client
Pre-validate/convert input in scripts before calling parse_tool_arguments

Example fix

# before
fastmcp client call my_tool --count abc
# after
fastmcp client call my_tool --count 42

Defensive patterns

Strategy: validation

Validate before calling

def is_integer_str(raw: str) -> bool:
    try:
        int(raw); return True
    except ValueError:
        return False

Type guard

def coerce_int(raw: str) -> int | None:
    try:
        return int(raw)
    except ValueError:
        return None

Try / catch

try:
    value = coerce_value(schema, raw)
except ValueError as exc:
    print(f'Invalid input: {exc}; expected an integer')
    raw = input('> ')

Prevention

Validate/convert CLI input with int() before passing it
Quote shell arguments and avoid locale-formatted digits
Prompt with an explicit example of the expected format

When it happens

Trigger: Calling a tool whose parameter schema is integer and supplying a non-integer string, e.g. 'abc', '' or '1.5', via parse_tool_arguments or an interactive terminal elicitation prompt.

Common situations: Typo'd or pasted input at the interactive prompt; shell arguments passed as unquoted text; scripts feeding raw user data straight into client tool calls.

Related errors

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/2e6f1df044d3af39. Report an issue: GitHub.