Improve Tracebacks for narrow terminals

[jlowin]

@strawgate curious if you 👍 . We've had considerably more requests to disable this than enable it :)

[strawgate]

There's a configuration for rich tracebacks that I use in another project that I've found is nice, basically limiting to 3 levels for the traceback and excluding FastMCP and mcp modules from the tracebacks.

I'm fine with just disabling outright but we could try just making them less bad first?

[strawgate]

Something like

handler.tracebacks_max_frames = 3
handler.tracebacks_suppress = [pydantic, fastmcp,mcp]

[jlowin]

Oh interesting, I wasn't aware -- happy to do that. I think the main reason for the dislike is that when they are narrow they are totally unusable (which I think you're wrestling with elsewhere for console width)

[strawgate]

I was planning on looking at console width tomorrow and will let you know if I find anything

[strawgate]

I made a quick project and deployed it to FastMCP cloud https://github.com/strawgate/py-mcp-terminal-size

And didn't discover anything revealing

Will play with it more today

[strawgate]

[09/29/25 13:17:27] INFO Causing traceback main.py:36 <-- this line is 80 characters
INFO <console width=80 None> main.py:39 <-- This line is 60 characters
╭─ Traceback (most recent cal─╮ <-- The traceback is 30 characters

[strawgate]

Basically I think what's happening is Rich sees the console as 80 characters wide
ERROR ................................tool_manager.py:233

It's a little misleading because fastmcp.cloud is stripping whitespace from the log line -- but here's what the actual layout really looks like (with a much wider width):

[09/29/25 07:57:33] INFO     Causing traceback                                                                                     main.py:36
                    INFO     <RichHandler (NOTSET)>                                                                                main.py:38
                    INFO     <console width=141 ColorSystem.TRUECOLOR>                                                             main.py:39
                    ERROR    Error calling tool 'cause_traceback'                                                         tool_manager.py:233
                             ╭─────────────────────────── Traceback (most recent call last) ────────────────────────────╮                    
                             │ /Users/bill.easton/repos/py-mcp-terminal-size/.venv/lib/python3.13/site-packages/fastmcp │                    
                             │ /tools/tool_manager.py:224 in call_tool                                                  │                    
                             │                                                                                          │                    
                             │   221 │   │   │   │   raise NotFoundError(f"Tool {key!r} not found")                     │                    
                             │   222 │   │   │                                                                          │                    
                             │   223 │   │   │   try:                                                                   │                    
                             │ ❱ 224 │   │   │   │   return await tool.run(arguments)                                   │                    
                             │   225 │   │   │                                                                          │                    
                             │   226 │   │   │   # raise ToolErrors as-is                                               │                    

The timestamp (which is blank if it's the same as the last one) plus LEVEL plus File plus Line Number leaves ~30 characters for the traceback if the console is limited to 80 characters wide.

[strawgate]

Using a specific handler for tracebacks where we don't include the error level or file path gives a lot more room for the traceback.

...
import fastmcp
import mcp
import pydantic

def configure_logging(
    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | int = "INFO",
    logger: logging.Logger | None = None,
    enable_rich_tracebacks: bool | None = None,
    **rich_kwargs: Any,
) -> None:
    """
    Configure logging for FastMCP.

    Args:
        logger: the logger to configure
        level: the log level to use
        rich_kwargs: the parameters to use for creating RichHandler
    """
    # Check if logging is disabled in settings
    if not fastmcp.settings.log_enabled:
        return

    # Use settings default if not specified
    if enable_rich_tracebacks is None:
        enable_rich_tracebacks = fastmcp.settings.enable_rich_tracebacks

    if logger is None:
        logger = logging.getLogger("fastmcp")

    formatter = logging.Formatter("%(message)s")

    # Only configure the FastMCP logger namespace
    handler = RichHandler(
        console=Console(stderr=True),
        rich_tracebacks=enable_rich_tracebacks,
        **rich_kwargs,
    )
    handler.setFormatter(formatter)

    # filter to exclude tracebacks
    handler.addFilter(lambda record: record.exc_info is None)

    traceback_handler = RichHandler(
        console=Console(stderr=True),
        show_path=False,
        show_level=False,
        rich_tracebacks=enable_rich_tracebacks,
        tracebacks_max_frames=3,
        tracebacks_suppress=[fastmcp,mcp,pydantic],
        **rich_kwargs,
    )
    traceback_handler.setFormatter(formatter)

    # filter to include tracebacks
    traceback_handler.addFilter(lambda record: record.exc_info is not None)

    logger.setLevel(level)

    # Remove any existing handlers to avoid duplicates on reconfiguration
    for hdlr in logger.handlers[:]:
        logger.removeHandler(hdlr)

    logger.addHandler(handler)
    logger.addHandler(traceback_handler)

    # Don't propagate to the root logger
    logger.propagate = False

[09/29/25 08:38:11] INFO     Causing traceback                                                                                     main.py:36
[09/29/25 08:38:11] Error calling tool 'cause_traceback'                                                                                     
                    ╭────────────────────────────────────────── Traceback (most recent call last) ──────────────────────────────────────────╮
                    │ /Users/bill.easton/repos/py-mcp-terminal-size/.venv/lib/python3.13/site-packages/fastmcp/tools/tool_manager.py:224 in │
                    │ call_tool                                                                                                             │
                    │                                                                                                                       │
                    │ /Users/bill.easton/repos/py-mcp-terminal-size/.venv/lib/python3.13/site-packages/fastmcp/tools/tool.py:314 in run     │
                    │                                                                                                                       │
                    │ /Users/bill.easton/repos/py-mcp-terminal-size/.venv/lib/python3.13/site-packages/pydantic/type_adapter.py:421 in      │
                    │ validate_python                                                                                                       │
                    │                                                                                                                       │
                    │ /Users/bill.easton/repos/py-mcp-terminal-size/main.py:40 in cause_traceback                                           │
                    │                                                                                                                       │
                    │   37 │   rich_handler: RichHandler = get_handlers_from_logger()[0]                                                    │
                    │   38 │   logger.info(str(rich_handler))                                                                               │
                    │   39 │   logger.info(str(rich_handler.console))                                                                       │
                    │ ❱ 40 │   raise Exception("Test exception")                                                                            │
                    │   41                                                                                                                  │
                    │   42 @mcp.tool()                                                                                                      │

[strawgate]

Here's what that looks like in fastmcp cloud

Double handlers is a bit messy but that does look a lot better to me, especially with the limited traceback depth and suppression of framework frames

[strawgate]

@jlowin i can implement this if you want otherwise we can proceed with whatever you think is best

[jlowin]

That does look cleaner but line 38 is still getting cut off in your most recent screenshot:

Is this a rich traceback thing where it censors the line? I guess I never looked closely at it

[strawgate]

Rich has an option to wrap the code lines, but it's off by default. We could enable it, but truncated has been fine for me.

This is the worst-case scenario, though, where the terminal is not dynamic and is limited to exactly 80 chars. As long as it shows enough code to point to the section that's causing the problem that's a big improvement.

With the limit of 3 for the frames perhaps enabling wrapping wouldn't even be that bad.

[strawgate]

@jlowin are you okay with me taking this over per the discussion above? or would you prefer to just keep it off?

[jlowin]

Totally fine if you want to take over, and also fine with default off as a sane rapid fallback if it doesn't work! @strawgate

[Copilot]

Pull Request Overview

This PR improves traceback display for narrow terminals by implementing a compressed traceback format. The change creates a dual-handler logging system: one for regular logs and another specifically for tracebacks with reduced visual clutter.

Key Changes:

• Splits logging into two handlers: one for normal logs (excluding tracebacks) and one dedicated to tracebacks
• Configures the traceback handler with compressed formatting (no path/level display) and limits frames to 3 with suppressed framework frames

[strawgate]

@jlowin updated and should be good to go
Before:

After:

[strawgate]

Interestingly -- the current state of the PR also seems to improve the performance of printing tracebacks by about 5x (reduce time spent in the richhandler by 80%).

In my test setup, printing 20 tracebacks takes 1s on main, 0.2s in this PR and 0.1s with rich tracebacks off

See #2053

[jlowin]

I can't submit a review bc it's my own PR but LGTM!