Refine structured error handler typing - #2827

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

Please add changelog entry in DESCRIPTION.md

I have read the CLA Document and I hereby sign the CLA

I’ve added a changelog entry in DESCRIPTION.md. Please let me know if anything else is needed or if you have any feedback.

Behavioral change in errorhandler_wrapper_from_ready_exception may bypass custom error handlers

The old implementation of errorhandler_wrapper_from_ready_exception routed all exceptions (including non-Error ones) through hand_to_other_handler, which would forward them to any custom errorhandler set on the cursor or connection. The new code immediately re-raises non-Error exceptions, skipping custom handlers entirely:

# New behavior
if not isinstance(error_exc, Error):
 raise error_exc

vs. the old behavior:

# Old behavior
else:
 error_value = error_exc.args
handed_over = Error.hand_to_other_handler(
 connection, cursor, type(error_exc), error_value,
)
if not handed_over:
 raise error_exc

The callers in cursor.py, aio/_cursor.py, and aio/_result_set.py all use isinstance(_next, Exception) as the guard, meaning arbitrary exceptions could flow in. In practice these exceptions come from Error.errorhandler_make_exception(InterfaceError, ...) in result_batch.py, so they should always be Error subclasses. But if any edge case produces a raw Exception, the behavior change would be user-visible:

1. Custom error handlers on cursor/connection would no longer see the exception
2. The messages list on cursor/connection wouldn't be appended to
3. The exception would bubble up raw instead of going through the handler chain

This is probably safe in practice, but it might be worth calling out explicitly as a deliberate behavior change — especially for anyone relying on custom errorhandler callbacks to intercept all exceptions.

Thanks for calling this out. This behavior change was intentional.

The goal of this PR was to align the structured error-handler path with the narrower contract used by the rest of the structured error machinery in errors.py: a Snowflake Error subclass together with a structured error payload.

Because of that, I changed errorhandler_wrapper_from_ready_exception() so that only Error instances are normalized and routed through the structured handler flow. Generic Python exceptions are now re-raised directly instead of being passed into the dict-based structured path.

I agree this is a behavioral change if a raw Exception reaches that wrapper. My intent was to make that boundary explicit rather than continue routing arbitrary exceptions through an API built around structured Snowflake error details. In the expected flow, callers reaching this wrapper should already be producing Snowflake Error instances.

Also, while the typing changes in this PR were made on the sync connection/cursor errorhandler attributes, the errorhandler_wrapper_from_ready_exception() change is in shared errors.py, so the runtime behavior change applies to both sync and async internal call sites that invoke that wrapper. The async connector does not expose the same public errorhandler API, so I did not make corresponding async attribute/property changes there.

I can update the PR description and changelog wording to make this behavior change more explicit, and I can also add async-path test coverage around the shared wrapper call sites if you’d like.

@abdulselamadillmohammed how crucial is this change? Any breaking change will require a major version bump which we want to avoid for now

Hi @sfc-gh-turbaszek ,

I’ve updated the logic to address the custom-handler and messages concerns you raised.

Non-Snowflake exceptions no longer bypass the handler chain. I've updated errorhandler_wrapper_from_ready_exception to call hand_to_other_handler for all exceptions, so connection.messages and cursor.messages are populated correctly and custom handlers can intercept the error. If nothing handles the exception, the original exception instance is re-raised rather than constructing a new one.

To keep the StructuredErrorHandler contract consistent, I am normalizing generic Python exceptions into an InterfaceError with a structured payload before passing them to handlers. This restores handler invocation and the messages updates, but it does still change what handlers see for generic exceptions: instead of the original Python exception class and args, handlers receive InterfaceError with a structured dict. I believe this is the cleanest way to preserve the structured handler contract while addressing the issues you pointed out, but please let me know if you’d prefer a closer restore of the old generic-exception behavior.