Python SDK: Use HatchetConfigurationError for invalid token validation by TheEleventhAvatar · Pull Request #3017 · hatchet-dev/hatchet

TheEleventhAvatar · 2026-02-13T16:17:03Z

Replace generic ValueError exceptions in ClientConfig token validation
with HatchetConfigurationError to better reflect configuration failures.

This improves clarity and aligns token validation with the SDK’s existing
exception hierarchy without changing runtime behavior.

Type of change

Refactor (non-breaking changes to code which doesn't change any behaviour)

What's Changed

Replace ValueError in token validation with HatchetConfigurationError
Ensure configuration-related failures consistently use the SDK's custom exception hierarchy
No changes to runtime logic or behavior

Notes

This change is intentionally scoped to token validation only and does not
modify other error handling paths.

Motivation

Using a domain-specific exception makes it easier for users of the SDK
to distinguish configuration errors from generic runtime failures.

Replace generic ValueError exceptions in ClientConfig token validation with HatchetConfigurationError to better reflect configuration failures. This improves clarity and aligns token validation with the SDK’s existing exception hierarchy without changing runtime behavior.

vercel · 2026-02-13T16:17:09Z

@TheEleventhAvatar is attempting to deploy a commit to the Hatchet Team on Vercel.

A member of the Team first needs to authorize it.

Copilot

Pull request overview

This PR aims to improve the Python SDK’s configuration error clarity by switching ClientConfig token-validation failures from generic ValueError to a domain-specific HatchetConfigurationError.

Changes:

Replace ValueError with HatchetConfigurationError for missing/invalid token validation in ClientConfig.
Update token validation error messages to be more configuration-focused (e.g., referencing HATCHET_CLIENT_TOKEN).
Remove a few explanatory inline comments in unrelated validators.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

sdks/python/hatchet_sdk/config.py

Copilot · 2026-02-13T16:21:28Z

sdks/python/hatchet_sdk/config.py

    @model_validator(mode="after")
    def validate_token_and_tenant(self) -> "ClientConfig":
        if not self.token:
-            raise ValueError("Token must be set")
+            raise HatchetConfigurationError(
+                "HATCHET_CLIENT_TOKEN must be set. "
+                "Provide it via environment variable or pass token=... to ClientConfig."
+            )

        if not self.token.startswith("ey"):
-            raise ValueError(
-                f"Token must be a valid JWT. Hint: These are the first few characters of the token provided: {self.token[:5]}"
+            raise HatchetConfigurationError(
+                "HATCHET_CLIENT_TOKEN must be a valid JWT. "
+                f"Received token starting with: '{self.token[:5]}...'"
            )


In Pydantic v2 validators, raising a non-ValueError/TypeError/AssertionError exception typically bypasses normal ValidationError aggregation and will change what callers see when ClientConfig() is constructed. If the intent is to keep Pydantic-style validation errors, make HatchetConfigurationError inherit from ValueError (or use PydanticCustomError); if the intent is to surface a domain-specific exception to users, consider catching ValidationError at the ClientConfig()/Hatchet() construction boundary and rethrowing HatchetConfigurationError there so behavior is explicit and consistent.

Copilot · 2026-02-13T16:21:29Z

sdks/python/hatchet_sdk/config.py

        if not self.token:
-            raise ValueError("Token must be set")
+            raise HatchetConfigurationError(
+                "HATCHET_CLIENT_TOKEN must be set. "
+                "Provide it via environment variable or pass token=... to ClientConfig."
+            )

        if not self.token.startswith("ey"):
-            raise ValueError(
-                f"Token must be a valid JWT. Hint: These are the first few characters of the token provided: {self.token[:5]}"
+            raise HatchetConfigurationError(
+                "HATCHET_CLIENT_TOKEN must be a valid JWT. "
+                f"Received token starting with: '{self.token[:5]}...'"
            )


Token validation now emits a different exception type/message, but there are no unit tests covering the missing-token and invalid-JWT paths. Add coverage in sdks/python/tests/test_client.py asserting the raised exception type (and key parts of the message) for ClientConfig(token="") and ClientConfig(token="not-a-jwt") so regressions are caught.

Copilot · 2026-02-13T16:21:29Z

sdks/python/hatchet_sdk/config.py

    @field_validator("event_loop_block_threshold_seconds", mode="before")
    @classmethod
    def validate_event_loop_block_threshold_seconds(
        cls, value: timedelta | int | float | str
    ) -> timedelta:
-        # Settings env vars are strings; interpret as seconds.
        if isinstance(value, timedelta):
            return value

        if isinstance(value, int | float):
            return timedelta(seconds=float(value))

        v = value.strip()
-        # Allow a small convenience suffix, but keep "seconds" as the contract.
        if v.endswith("s"):
            v = v[:-1].strip()


PR description says the change is scoped to token validation only, but this diff also removes explanatory comments in the healthcheck threshold validator. Either keep the scope strictly to token validation (revert these comment-only edits) or update the PR description to reflect the additional changes.

@copilot open a new pull request to apply changes based on this feedback

Copilot · 2026-02-13T16:21:29Z

sdks/python/hatchet_sdk/config.py

    @model_validator(mode="after")
    def validate_addresses(self) -> "ClientConfig":
-        ## If nothing is set, read from the token
-        ## If either is set, override what's in the JWT
        server_url_from_jwt, grpc_broadcast_address_from_jwt = get_addresses_from_jwt(
            self.token
        )


PR description notes the change is intentionally scoped to token validation only, but this diff also removes comments describing how validate_addresses derives overrides from the JWT. Either revert the comment-only edits here or adjust the PR description/scope accordingly.

@copilot open a new pull request to apply changes based on this feedback

mrkaye97

AFAICT, HatchetConfigurationError is never actually defined?

TheEleventhAvatar · 2026-02-13T16:39:05Z

AFAICT, HatchetConfigurationError is never actually defined?

Good catch — thanks! I’ve now defined HatchetError and HatchetConfigurationError in hatchet_sdk/exceptions.py and updated the import accordingly.

mrkaye97 · 2026-02-13T16:41:14Z

AFAICT, HatchetConfigurationError is never actually defined?

Good catch — thanks! I’ve now defined HatchetError and HatchetConfigurationError in hatchet_sdk/exceptions.py and updated the import accordingly.

Maybe I'm missing it - I don't see that change

TheEleventhAvatar · 2026-02-13T16:42:54Z

AFAICT, HatchetConfigurationError is never actually defined?

Good catch — thanks! I’ve now defined HatchetError and HatchetConfigurationError in hatchet_sdk/exceptions.py and updated the import accordingly.

Maybe I'm missing it - I don't see that change

now it is there!

mrkaye97 · 2026-02-13T16:44:05Z

sdks/python/hatchet_sdk/exceptions.py

+class HatchetError(Exception):
+    """Base exception for Hatchet Python SDK."""
+
+
+class HatchetConfigurationError(HatchetError):
+    """Raised when required configuration is missing or invalid."""


so unfortunately, as this is defined it's a breaking change. If we want to replace instances of ValueError with these exceptions, they need to inherit from ValueError

Good point — thanks for calling that out. I’ve updated HatchetConfigurationError to inherit from ValueError to avoid introducing a breaking change.

mrkaye97 · 2026-02-13T17:22:11Z

sdks/python/hatchet_sdk/config.py

    def validate_event_loop_block_threshold_seconds(
        cls, value: timedelta | int | float | str
    ) -> timedelta:
-        # Settings env vars are strings; interpret as seconds.


let's leave this comment

mrkaye97 · 2026-02-13T17:22:37Z

sdks/python/hatchet_sdk/config.py

    @model_validator(mode="after")
    def validate_addresses(self) -> "ClientConfig":
-        ## If nothing is set, read from the token
-        ## If either is set, override what's in the JWT


let's leave these comments

mrkaye97 · 2026-02-13T17:23:07Z

Thanks for the contribution! Left a couple small notes - we also need to bump the patch version of the package and add a new changelog entry

TheEleventhAvatar · 2026-02-13T17:44:04Z

Thanks for the contribution! Left a couple small notes - we also need to bump the patch version of the package and add a new changelog entry

there is no version file,do you handle it via tags or CI/CD?i did changelog entry

mrkaye97 · 2026-02-13T17:45:12Z

Thanks for the contribution! Left a couple small notes - we also need to bump the patch version of the package and add a new changelog entry

there is no version file,do you handle it via tags or CI/CD?i did changelog entry

it's in the pyproject.toml

TheEleventhAvatar · 2026-02-13T17:54:44Z

Thanks for the contribution! Left a couple small notes - we also need to bump the patch version of the package and add a new changelog entry

there is no version file,do you handle it via tags or CI/CD?i did changelog entry

it's in the pyproject.toml

updated pyproject and changelog

TheEleventhAvatar · 2026-02-14T10:13:33Z

@mrkaye97 formatted only the exceptions file,.lint check now passes

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-14T14:48:30Z

sdks/python/hatchet_sdk/config.py

        if not self.token:
-            raise ValueError("Token must be set")
+            raise HatchetConfigurationError(
+                "HATCHET_CLIENT_TOKEN must be set. "
+                "Provide it via environment variable or pass token=... to ClientConfig."
+            )


Token validation behavior changed (exception type/message). There are existing tests covering ClientConfig construction, but none assert the error behavior for missing/invalid tokens. Add unit tests that verify missing token and malformed token cases raise the expected configuration error (and, if required for backwards-compat, that it remains a ValueError subclass).

Copilot · 2026-02-14T14:48:30Z

sdks/python/hatchet_sdk/config.py

    @field_validator("event_loop_block_threshold_seconds", mode="before")
    @classmethod
    def validate_event_loop_block_threshold_seconds(
        cls, value: timedelta | int | float | str
    ) -> timedelta:
-        # Settings env vars are strings; interpret as seconds.
        if isinstance(value, timedelta):


This hunk contains comment-only edits unrelated to token validation (the PR description says the change is intentionally scoped to token validation only). Either revert these comment-only changes here or update the PR description/scope to reflect the additional edits.

Copilot · 2026-02-14T14:48:31Z

sdks/python/CHANGELOG.md

+#### Changed
+- Python SDK `ClientConfig` token validation now raises `HatchetConfigurationError` instead of `ValueError` for invalid or missing configuration.
+- Minor field validators updated to improve clarity and robustness.
+- Updated package patch version to include these non-breaking improvements.



The changelog entry appears to (1) change the heading level from ### Changed to #### Changed (inconsistent with other entries) and (2) replace prior 1.23.4 bullets with new ones that mention changes (e.g., patch version bump / validator updates) that aren’t present in this PR. Please keep the changelog formatting consistent and ensure the 1.23.4 notes accurately reflect the actual code changes in this PR.

Suggested change

#### Changed

- Python SDK `ClientConfig` token validation now raises `HatchetConfigurationError` instead of `ValueError` for invalid or missing configuration.

- Minor field validators updated to improve clarity and robustness.

- Updated package patch version to include these non-breaking improvements.

### Changed

- Documentation-only updates to the changelog; no functional changes to the Python SDK.

Copilot · 2026-02-14T14:48:31Z

sdks/python/hatchet_sdk/exceptions.py

HatchetConfigurationError is introduced as a new public exception type, but it isn't re-exported from hatchet_sdk.__init__ (unlike the other exceptions). Consider adding it to the package exports (__init__.py imports / __all__) so users can reliably import it from hatchet_sdk like the rest of the SDK exceptions.

Suggested change

__all__ = [

"HatchetConfigurationError",

"InvalidDependencyError",

"NonRetryableException",

"DedupeViolationError",

"TASK_RUN_ERROR_METADATA_KEY",

"TaskRunError",

"FailedTaskRunExceptionGroup",

"LoopAlreadyRunningError",

"IllegalTaskOutputError",

"LifespanSetupError",

]

Copilot AI review requested due to automatic review settings February 13, 2026 16:17

Merge branch 'main' into python/use-configuration-error-for-token

a313760

Copilot started reviewing on behalf of TheEleventhAvatar February 13, 2026 16:17 View session

TheEleventhAvatar mentioned this pull request Feb 13, 2026

[FEAT] Improve Python SDK error messages for missing or invalid configuration #2879

Closed

Copilot AI reviewed Feb 13, 2026

View reviewed changes

mrkaye97 requested changes Feb 13, 2026

View reviewed changes

python: define HatchetError and HatchetConfigurationError

b26d68e

mrkaye97 reviewed Feb 13, 2026

View reviewed changes

python: make HatchetConfigurationError inherit from ValueError

7dd9658

mrkaye97 reviewed Feb 13, 2026

View reviewed changes

chore(python-sdk): update changelog for HatchetConfigurationError

29820f3

chore(python-sdk): bump patch version to 1.23.4 and update changelog

de43b9e

TheEleventhAvatar added 2 commits February 13, 2026 23:26

Merge branch 'main' into python/use-configuration-error-for-token

c82ef9e

Merge branch 'main' into python/use-configuration-error-for-token

7075531

TheEleventhAvatar requested a review from mrkaye97 February 14, 2026 09:33

TheEleventhAvatar force-pushed the python/use-configuration-error-for-token branch 2 times, most recently from 35b4524 to 7075531 Compare February 14, 2026 09:57

TheEleventhAvatar added 2 commits February 14, 2026 10:05

python: apply Black formatting to modified files

269bf4b

reformatted exceptions.py

5fb39db

TheEleventhAvatar requested a review from Copilot February 14, 2026 14:42

Copilot started reviewing on behalf of TheEleventhAvatar February 14, 2026 14:42 View session

Copilot AI reviewed Feb 14, 2026

View reviewed changes

Merge branch 'main' into python/use-configuration-error-for-token

1a2eeea

+__all__ = [
+    "HatchetConfigurationError",
+    "InvalidDependencyError",
+    "NonRetryableException",
+    "DedupeViolationError",
+    "TASK_RUN_ERROR_METADATA_KEY",
+    "TaskRunError",
+    "FailedTaskRunExceptionGroup",
+    "LoopAlreadyRunningError",
+    "IllegalTaskOutputError",
+    "LifespanSetupError",
+]

Conversation

TheEleventhAvatar commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of change

What's Changed

Notes

Motivation

Uh oh!

vercel bot commented Feb 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

TheEleventhAvatar Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

TheEleventhAvatar Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

mrkaye97 left a comment

Choose a reason for hiding this comment

Uh oh!

TheEleventhAvatar commented Feb 13, 2026

Uh oh!

mrkaye97 commented Feb 13, 2026

Uh oh!

TheEleventhAvatar commented Feb 13, 2026

Uh oh!

mrkaye97 Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

TheEleventhAvatar Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

mrkaye97 Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

mrkaye97 Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

mrkaye97 commented Feb 13, 2026

Uh oh!

TheEleventhAvatar commented Feb 13, 2026

Uh oh!

mrkaye97 commented Feb 13, 2026

Uh oh!

TheEleventhAvatar commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TheEleventhAvatar commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 14, 2026

TheEleventhAvatar commented Feb 13, 2026 •

edited

Loading

TheEleventhAvatar commented Feb 13, 2026 •

edited

Loading

TheEleventhAvatar commented Feb 14, 2026 •

edited

Loading