Skip to content

Fix unstructured tool errors being masked as 'outputSchema defined but no structured output returned'#781

Merged
jairus-m merged 3 commits into
mainfrom
bug/output-validation-error
May 19, 2026
Merged

Fix unstructured tool errors being masked as 'outputSchema defined but no structured output returned'#781
jairus-m merged 3 commits into
mainfrom
bug/output-validation-error

Conversation

@jairus-m
Copy link
Copy Markdown
Collaborator

@jairus-m jairus-m commented May 15, 2026

Summary

When a tool raised an exception, DbtMCP.call_tool() caught it and returned [TextContent(...)] which is unstructured. After #774 changed structured_output to default to True, all tools gained an outputSchema. Because of this, the MCP server rejects the unstructured error response with "Output validation error: outputSchema defined but no structured output returned". The actual error is not returned and hidden to the user/LLM:

Screenshot 2026-05-15 at 8 46 38 AM

To address this, we instead return CallToolResult(isError=True) on exception so the MCP server "short circuits" raise an error which gets caught by FastMCP's handler before the outputSchema check which then properly outputs the failure:

Screenshot 2026-05-15 at 8 46 16 AM

Checklist

  • I have performed a self-review of my code
  • I have made corresponding changes to the documentation (in https://github.com/dbt-labs/docs.getdbt.com) if required -- Mention it here
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes

Additional Notes

One thing Im unsure about about this implementation here is that we have to override the return type established by the parent FastMCP.call_tool method and add CallToolResult to DbtMCP.call_tool's annotations. Because of this, mypy gets a bit mad and we have to tell it to "shhh". No behavioral changes with regards to the LSP, just type annotations! Hope this is fine.

^^ addressed in comments

@jairus-m jairus-m requested review from a team, b-per and jasnonaz as code owners May 15, 2026 16:33
Comment thread src/dbt_mcp/mcp/server.py Outdated
Comment thread src/dbt_mcp/mcp/server.py Outdated
…_tool return types (error gets propfated and caught by FastMCP's handler)
@jairus-m jairus-m enabled auto-merge (squash) May 15, 2026 21:18
@jairus-m jairus-m merged commit 11951fd into main May 19, 2026
7 checks passed
@jairus-m jairus-m deleted the bug/output-validation-error branch May 19, 2026 09:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants