Address various entity-related bugs #109

andystaples · 2026-02-09T20:49:14Z

Addresses the following issues:

EntityInstanceId was not correctly treating entity names as type-insensitive, leading to issues where "counter" and "Counter" were treated as two separate entity types, contrasting with other SDKs and backends where these would be normalized to "counter".
a. NOTE: The fix for this (normalizing entity names to lowercase) is a breaking change under the following scenarios:
- Calling register_entity(counter) and register_entity(Counter) on the same worker will now fail
- Direct checks against EntityInstanceId.name (e.g. instance_id.name == 'Counter') may break
EntityInstanceId was not correctly checking against some invalid cases for instance ID
Returning a non-encodable object as the result of an orchestration would cause the orchestration to never complete (see Bug: Returning an exception object as the result of an orchestration causes it to never complete #108). This now returns a string with an error message including the stringified version of the object that failed to encode, but I'm also open to just outright failing the orchestration.
Entity failures were not handled correctly, leading to hung orchestrations.
a. Now, entity failures are handled like any other task failure by the orchestrator, and returned to user code as an EntityOperationFailedException wrapped in a TaskFailedError.
Previously, we were saving a state dictionary of all registered entities, this was essentially a memory leak for long-lived workers that processed many different entity instances and provided no tangible benefit, so this functionality has been removed. Entities will be re-created for each invocation (matching the .NET behavior)

Resolves #108

andystaples · 2026-02-09T20:52:01Z

durabletask/worker.py

+            try:
+                result_json = result if is_result_encoded else shared.to_json(result)
+            except TypeError:
+                result_json = shared.to_json(str(JsonEncodeOutputException(result)))


Reviewers - this is the "safe" approach where a return value that we cannot process to json is instead stringified along with an error message. I believe the other SDKs would just fail the orchestration outright - is this preferable here too?

Copilot

Pull request overview

This PR fixes several Durable Entities correctness issues in the Python SDK, aligning behavior with other Durable Task SDKs/backends (notably around entity ID normalization, entity failure propagation, and orchestration completion semantics).

Changes:

Normalize EntityInstanceId.entity and registered entity names to lowercase and tighten entity ID parsing validation.
Propagate entityOperationFailed events as task failures surfaced to user code (via TaskFailedError wrapping an EntityOperationFailedException).
Prevent orchestrations from hanging when user code returns a non-JSON-encodable result, and add extensive DTS (sidecar/emulator) E2E coverage for entities.

Reviewed changes

Copilot reviewed 7 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/durabletask/entities/test_entity_id_parsing.py	Adds unit coverage for entity ID parsing and case-insensitivity.
tests/durabletask-azuremanaged/entities/test_dts_function_based_entities_e2e.py	Adds DTS E2E coverage for function-based entity scenarios (signal/call/locks/unlocks).
tests/durabletask-azuremanaged/entities/test_dts_entity_failure_handling.py	Adds DTS E2E coverage for entity operation failures and lock recovery behavior.
tests/durabletask-azuremanaged/entities/test_dts_class_based_entities_e2e.py	Adds DTS E2E coverage for class-based entities and custom names.
tests/durabletask-azuremanaged/entities/init.py	Introduces entities test package module.
durabletask/worker.py	Implements lowercase entity registration, removes cached entity instances, adds entity failure handling, and guards orchestration completion encoding.
durabletask/internal/json_encode_output_exception.py	Adds a custom exception type used to describe JSON encoding failures for orchestration outputs.
durabletask/entities/entity_operation_failed_exception.py	Defines a typed exception for failed entity operations (used for user-visible failures).
durabletask/entities/entity_instance_id.py	Lowercases entity names and hardens parsing against invalid formats.
durabletask/entities/init.py	Exposes `EntityOperationFailedException` as part of the public entities API.

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

durabletask/entities/entity_instance_id.py

durabletask/worker.py

tests/durabletask-azuremanaged/entities/test_dts_entity_failure_handling.py

durabletask/entities/entity_instance_id.py

halspang

Seems fine overall, just a few questions.

halspang · 2026-02-09T21:48:46Z

durabletask/entities/entity_instance_id.py

+        if "@" in key:
+            raise ValueError("Entity key cannot contain '@' symbol.")


This can also be a breaking change unless we had other ways of filtering this that were already present.

halspang · 2026-02-09T22:00:30Z

durabletask/internal/json_encode_output_exception.py

+        self.problem_object = problem_object
+
+    def __str__(self) -> str:
+        return f"The orchestration result could not be encoded. Object details: {self.problem_object}"


For my own edification, how does this encode into JSON? From the name of the class, I would also assume that the output of this class is JSON not just the raw string, but if this is the python standard that's fine.

halspang · 2026-02-09T22:02:03Z

durabletask/worker.py

@@ -201,6 +201,7 @@ def add_entity(self, fn: task.Entity, name: Optional[str] = None) -> str:
    def add_named_entity(self, name: str, fn: task.Entity) -> None:


Should we have the @ check here as well?

halspang · 2026-02-09T22:24:27Z

durabletask/worker.py

    orchestrators: dict[str, task.Orchestrator]
    activities: dict[str, task.Activity]
    entities: dict[str, task.Entity]
-    entity_instances: dict[str, DurableEntity]


I know this is the intended fix for the leak issues, but will this have a significant impact on performance? Seems like an idle purge is a better solution, but if the creation is basically a no-op, I think this could be fine too. Just want to make sure we're considering both sides.

halspang · 2026-02-09T22:28:00Z

durabletask/worker.py

    def add_named_entity(self, name: str, fn: task.Entity) -> None:
        if not name:
            raise ValueError("A non-empty entity name is required.")
+        name = name.lower()


It won't let me comment in the test file, but do we have a test for registering an entity with different casing working?

Address various entity-related bugs

b97434d

andystaples requested review from berndverst, cgillum, Copilot and torosent February 9, 2026 20:49

andystaples self-assigned this Feb 9, 2026

Copilot started reviewing on behalf of andystaples February 9, 2026 20:49 View session

andystaples commented Feb 9, 2026

View reviewed changes

Copilot AI reviewed Feb 9, 2026

View reviewed changes

andystaples and others added 2 commits February 9, 2026 14:00

PR feedback

ffdabaa

Merge branch 'main' into andystaples/entity-improvements

bb8243e

andystaples requested a review from halspang February 9, 2026 21:19

halspang reviewed Feb 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Address various entity-related bugs #109

Address various entity-related bugs #109

andystaples commented Feb 9, 2026 •

edited

Loading

Uh oh!

andystaples Feb 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

halspang left a comment

Uh oh!

halspang Feb 9, 2026

Uh oh!

halspang Feb 9, 2026

Uh oh!

halspang Feb 9, 2026

Uh oh!

halspang Feb 9, 2026

Uh oh!

halspang Feb 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		if "@" in key:
		raise ValueError("Entity key cannot contain '@' symbol.")

		@@ -201,6 +201,7 @@ def add_entity(self, fn: task.Entity, name: Optional[str] = None) -> str:
		def add_named_entity(self, name: str, fn: task.Entity) -> None:

Address various entity-related bugs #109

Are you sure you want to change the base?

Address various entity-related bugs #109

Conversation

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

Uh oh!

Uh oh!

andystaples Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

halspang left a comment

Choose a reason for hiding this comment

Uh oh!

halspang Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

halspang Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

halspang Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

halspang Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

halspang Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

andystaples commented Feb 9, 2026 •

edited

Loading