PrefectHQ/fastmcp · error · TypeError

Invalid first argument: {type(name_or_fn)}

Error message

Invalid first argument: {type(name_or_fn)}

What it means

After checking for a routine, string, and None, any other type for the first positional argument of `@prompt` (e.g. a Prompt instance, class, list) is rejected with this TypeError. The first argument must be a function, a name string, or omitted.

Source

Thrown at fastmcp_slim/fastmcp/server/providers/local_provider/decorators/prompts.py:215

            target = fn.__func__ if hasattr(fn, "__func__") else fn
            target.__fastmcp__ = metadata  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
            self.add_prompt(fn)
            return fn

        if inspect.isroutine(name_or_fn):
            return decorate_and_register(name_or_fn, name)

        elif isinstance(name_or_fn, str):
            if name is not None:
                raise TypeError(
                    f"Cannot specify both a name as first argument and as keyword argument. "
                    f"Use either @prompt('{name_or_fn}') or @prompt(name='{name}'), not both."
                )
            prompt_name = name_or_fn
        elif name_or_fn is None:
            prompt_name = name
        else:
            raise TypeError(f"Invalid first argument: {type(name_or_fn)}")

        return partial(
            self.prompt,
            name=prompt_name,
            version=version,
            title=title,
            description=description,
            icons=icons,
            tags=tags,
            meta=meta,
            enabled=enabled,
            auth=auth,
        )

View on GitHub (pinned to 1f02114297)

Solutions

1. Pass a string name: `@prompt('my_name')`, or omit the argument entirely: `@prompt`
2. If you meant to register an existing Prompt, use `add_prompt(prompt_instance)` instead of the decorator
3. Quote the name if you wrote `@prompt(my_name)` where `my_name` is an unresolved variable

Example fix

// before
@provider.prompt(my_prompt_name)  # variable is undefined/None
async def p(): ...
// after
@provider.prompt('my_prompt_name')
async def p(): ...

assert isinstance(name_or_fn, (str, type(None))) or callable(name_or_fn), 'first arg must be str, callable, or omitted'

def valid_prompt_arg(x) -> bool:
    import inspect
    return x is None or isinstance(x, str) or inspect.isroutine(x)

try:
    deco = provider.prompt(name_or_fn)
except TypeError as e:
    if 'Invalid first argument' in str(e): fix_signature()

When it happens

Trigger: `@prompt(some_prompt_instance)`, `@prompt(MyClass)`, or accidentally calling with a non-str non-callable first argument like `@prompt(123)`.

Common situations: Passing a Prompt object where a name string was intended; typos such as forgetting quotes around the name; reusing decorator snippets across tool/prompt APIs with different signatures.

Related errors

• messages[{i}] must be Message, got {type(item).__name__}. Us
• messages must be str or list[Message], got {type(messages)._
• messages[{i}] must be Message or str, got {type(item).__name
• Prompt must return str, list[Message], or PromptResult, got
• Expected Prompt or @prompt-decorated function, got {type(pro

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