PrefectHQ/fastmcp · error · PromptError

Error rendering prompt {name!r}: {e}

Error message

Error rendering prompt {name!r}: {e}

What it means

The detail-preserving variant of the prompt rendering failure: when self._mask_error_details is False, FastMCP converts the underlying exception to PromptError whose message appends the original error text (': {e}'), preserving diagnostic detail while still normalizing the type.

Source

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

                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(
        self,

View on GitHub (pinned to 1f02114297)

Solutions

1. Inspect the ': {e}' suffix — it contains the original error; fix that root cause
2. Correct the arguments passed to get_prompt
3. Add validation or explicit PromptError raising inside the prompt function

Example fix

// before
await mcp.get_prompt("summary", {"doc": None})  # NoneType error in render
// after
await mcp.get_prompt("summary", {"doc": open("report.md").read()})

assert all(k in arguments for k in prompt_fn_signature_params)

try:
    prompt = await mcp.get_prompt(name, arguments)
except PromptError as e:
    print(e)  # message includes original ': {e}' detail

When it happens

Trigger: server.get_prompt()/render_prompt() where the prompt function raises a non-MCP Exception and mask_error_details is False.

Common situations: Development/staging servers where error details are intentionally exposed; misconfigured prompt arguments producing ValueError/KeyError inside the render function.

Related errors

• Error rendering prompt {name!r}
• 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/de54d41db91defb5. Report an issue: GitHub.