SNOW-3246741: Align structured error-handler typing and ready-exception handling

[abdulselamadillmohammed]

I believe I've found an inconsistency in the connector’s structured error-handling flow and wanted maintainer feedback before opening a PR.

The connection/cursor errorhandler typing is looser and less explicit than the structured Error-based contract used in errors.py. There is also a mismatch in the ready-exception path: generic Python exceptions can be routed into the structured handler flow even though that flow expects structured error details rather than Exception.args-style payloads.

I prepared a branch with a proposed fix:

• branch: typing-errorhandler-protocol

The change does the following:

• introduces a shared structured payload type for error-handler details
• introduces a shared structured handler protocol
• aligns connection.py and cursor.py with that structured contract
• narrows the structured path to Error subclasses
• updates the ready-exception wrapper so generic exceptions are re-raised instead of being routed into the dict-based structured handler flow
• adds unit tests for the structured and ready-exception paths

Before opening the PR, I wanted to confirm:

1. whether maintainers agree this should be treated as an internal bug/consistency fix
2. whether narrowing the structured path to Error subclasses is the right direction
3. whether this should go in as one PR or be split into smaller pieces

[sfc-gh-sghosh]

Hello @abdulselamadillmohammed ,

Thanks for raising the concern.

Yes, the flow for error handling is supposed to work as below:

Something goes wrong inside the connector

• The connector builds a dictionary like {"msg": "bad query", "errno": 123, "sqlstate": "42000"}
• This dict gets passed to your custom error handler (if you set one) or the default one
• The handler reads error_value["msg"], error_value["errno"], etc. and raises a proper exception
• This works perfectly for Snowflake's own errors (ProgrammingError, DatabaseError, etc.)

But sometimes a generic Python exception (like ValueError, RuntimeError) happens inside the connector. When that gets routed through the same error handling path:

ValueError("something went wrong") is created
The connector checks: "Is this a Snowflake Error?" → No
So instead of building a dict, it does: error_value = error_exc.args
.args on a generic exception is a tuple: ("something went wrong",)
Next function (hand_to_other_handler) tries to call error_value.setdefault("done_format_msg", False)
Tuples don't have .setdefault() → AttributeError → CRASH

Snowflake Error (ProgrammingError):
  → builds dict {"msg": "...", "errno": 123}
  → dict.setdefault("done_format_msg", False) ->  works
  → your custom handler receives the dict       -> works

Generic Exception (ValueError):
  → uses error_exc.args = ("something went wrong",)  ← tuple!
  → tuple.setdefault(...)                     ->    AttributeError CRASH
  → your custom handler                      ->     never reached

So, there seems inconsistency which is why its throwing above AttributeError error.
This is a reasonable direction. Generic exceptions should either be re-raised directly or wrapped into an
appropriate Error subclass before entering the structured handler flow -- not passed through as-is.

Let me update you on this before raising the PR.

[abdulselamadillmohammed]

Thanks for confirming the inconsistency and the expected flow.

That matches what I was seeing. I’ll hold off on opening the PR until I hear back from you. I already have a branch with a proposed fix and tests, and I’m happy to adjust the approach based on maintainer guidance before opening the PR.

[sfc-gh-turbaszek]

@abdulselamadillmohammed please feel encouraged to open a PR

[abdulselamadillmohammed]

@sfc-gh-turbaszek Thank you, just opened a PR.