PrefectHQ/fastmcp · error · PromptError

Error rendering prompt {name!r}

Error message

Error rendering prompt {name!r}

What it means

This generic wrapper is raised by FastMCP.render_prompt when an unhandled exception occurs while rendering a prompt's messages/arguments. If the original error is an MCPError it is re-raised unchanged (error 540 is the log line accompanying the re-raise); otherwise the server converts it to PromptError. With mask_error_details enabled the original exception text is hidden.

Source

Thrown at fastmcp_slim/fastmcp/server/server.py:1792

            ) as span:
                prompt = await self.get_prompt(name, version=version)
                if prompt is None:
                    raise NotFoundError(f"Unknown prompt: {name!r}")
                span.set_attributes(prompt.get_span_attributes())
                try:
                    return await prompt._render(arguments)
                except FastMCPError as e:
                    logger.log(
                        e.log_level, f"Error rendering prompt {name!r}", exc_info=True
                    )
                    raise
                except MCPError:
                    logger.exception(f"Error rendering prompt {name!r}")
                    raise
                except Exception as e:
                    logger.exception(f"Error rendering prompt {name!r}")
                    if self._mask_error_details:
                        raise PromptError(f"Error rendering prompt {name!r}") from e
                    raise PromptError(f"Error rendering prompt {name!r}: {e}") from e

    def add_tool(self, tool: Tool | Callable[..., Any]) -> Tool:
        """Add a tool to the server.

        The tool function can optionally request a Context object by adding a parameter
        with the Context type annotation. See the @tool decorator for examples.

        Args:
            tool: The Tool instance or @tool-decorated function to register

        Returns:
            The tool instance that was added to the server.
        """
        return self._local_provider.add_tool(tool)

    @overload
    def tool(

View on GitHub (pinned to 1f02114297)

Solutions

1. Read the chained exception (__cause__) or server logs (logger.exception prints the full traceback) to find the root cause
2. Fix the prompt function or pass correct/complete arguments to get_prompt
3. Disable mask_error_details in development so the error message includes the underlying '{e}' detail
4. Wrap known failure modes in your prompt function and raise MCPError/PromptError directly so they pass through unmasked

Example fix

// before
prompt = await mcp.get_prompt("greet")  # missing required argument
// after
prompt = await mcp.get_prompt("greet", {"name": "Alice"})

# ensure required args are present before rendering
missing = required_args - set(arguments or {})
if missing:
    raise ValueError(f"missing prompt arguments: {missing}")

try:
    prompt = await mcp.get_prompt("greet", arguments)
except PromptError as e:
    logger.error("prompt render failed: %s", e.__cause__)

When it happens

Trigger: Calling server.get_prompt(name, arguments) or render_prompt() when the prompt's render function raises a non-MCP exception (bad arguments, bug in the prompt function, missing template variables).

Common situations: Typo in prompt argument names; prompt function references missing context; template rendering fails on None arguments; a middleware chain raises an unexpected exception type.

Related errors

• Error rendering prompt {name!r}: {e}
• messages[{i}] must be Message, got {type(item).__name__}. Us
• messages must be str or list[Message], got {type(messages)._
• Subclasses must implement render()
• messages[{i}] must be Message or str, got {type(item).__name

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