Improve error message for type engine

[pingsutw]

Tracking issue

NA

Why are the changes needed?

Improve the error message so people can debug much more easily.

What changes were proposed in this pull request?

• Update repr for LiteralType
• Update the error message for wrong inputs/outputs/bindings

How was this patch tested?

from datetime import datetime, date
from enum import StrEnum
from typing import Any

from click.testing import CliRunner

from flytekit import task, workflow, ImageSpec, dynamic
from flytekit.clis.sdk_in_container import pyflyte

new_flytekit = "git+https://github.com/flyteorg/flytekit.git@d341be82f4291e48fc0ccd2e53a59bcd22273d4f"

image = ImageSpec(
    # registry="ghcr.io/flyteorg",
    packages=[new_flytekit, "gcsfs==2025.7.0", "fsspec==2025.7.0"],
    apt_packages=["git"],
    builder="union"
)


class ArtifactRelType(StrEnum):
    DOWNSTREAM_OF = "downstream_of"
    RELATED_TO = "related_to"


FlytePropertyValue = float | None | str | bool | datetime | date | list[str]


@task(container_image=image)
def say_hello(
    my_val: dict[str, float | int],
    artifact_rel_type: dict[str, ArtifactRelType] | None = None,
    additional_properties: dict[str, FlytePropertyValue] | None = None,
) -> dict[str, float | int]:
    print(my_val)
    return my_val


@task(container_image=image)
def gen_outputs(
) -> dict[str, FlytePropertyValue] | None:
    return [{"c": ["hello"], "algorithm": "xgboost"}]


@task(container_image=image)
def gen_outputs1(
) -> list[dict[str, FlytePropertyValue]] | dict[str, FlytePropertyValue] | None:
    return [{"c": ["hello"], "algorithm": "xgboost"}]


@workflow
def wf():
    # Wrong outputs
    # union run --remote flyte-example/fix_type.py wf
    say_hello(
        my_val={"a": 1, "b": 2},
        artifact_rel_type={"a": ArtifactRelType.DOWNSTREAM_OF},
        additional_properties=gen_outputs(),
    )


@workflow
def wf1():
    # Wrong binding
    # union run --remote flyte-example/fix_type.py wf1
    say_hello(
        my_val={"a": 1, "b": 2},
        artifact_rel_type={"a": ArtifactRelType.DOWNSTREAM_OF},
        additional_properties=[{"c": ["hello"], "algorithm": "xgboost"}],
    )


@workflow()
def wf2(additional_properties: dict[str, FlytePropertyValue] | None = [{"c": ["hello"], "algorithm": "xgboost"}]):
    # Wrong default inputs
    # union run --remote flyte-example/fix_type.py wf2
    say_hello(
        my_val={"a": 1, "b": 2},
        artifact_rel_type={"a": ArtifactRelType.DOWNSTREAM_OF},
        additional_properties=additional_properties,
    )


@workflow()
def wf3():
    # Wrong inputs
    # union run flyte-example/fix_type.py wf3
    res = gen_outputs1()
    say_hello(
        my_val={"a": 1, "b": 2},
        artifact_rel_type={"a": ArtifactRelType.DOWNSTREAM_OF},
        additional_properties=res,
    )

Setup process

Screenshots

Before:

TypeTransformerFailedError: Error encountered while converting inputs of 'fix_type.say_hello':
  Error converting input 'additional_properties' at position 2:
Literal value: Flyte Serialized object (Literal):
  scalar:
    union:
      value:
        collection:
          literals: [map { literals { key: "c" value { scalar { union { value { collection { [...]
      type:
        collection_type:
          map_value_type:
            union_type:
              variants: [simple: FLOAT structure { tag: "float" } , simple: NONE structure { tag: [...]
        structure:
          tag: Typed List
Expected Python type: dict[str, float | None | str | bool | datetime.datetime | datetime.date | list[str]] | None
Exception: Cannot convert from Flyte Serialized object (Literal):
  scalar:
    union:
      value:
        collection:
          literals: [map { literals { key: "c" value { scalar { union { value { collection { [...]
      type:
        collection_type:
          map_value_type:
            union_type:
              variants: [simple: FLOAT structure { tag: "float" } , simple: NONE structure { tag: [...]
        structure:
          tag: Typed List to dict[str, float | None | str | bool | datetime.datetime | datetime.date | list[str]] | None (using tag Typed List)

After:

Trace:

    Traceback (most recent call last):
      File "/opt/micromamba/envs/runtime/lib/python3.12/site-packages/flytekit/core/base_task.py", line 767, in dispatch_execute
        native_outputs = self.execute(**native_inputs)
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/opt/micromamba/envs/runtime/lib/python3.12/site-packages/flytekit/core/python_function_task.py", line 216, in execute
        return self.dynamic_execute(self._task_function, **kwargs)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/opt/micromamba/envs/runtime/lib/python3.12/site-packages/flytekit/core/python_function_task.py", line 370, in dynamic_execute
        return self.compile_into_workflow(ctx, task_function, **kwargs)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/opt/micromamba/envs/runtime/lib/python3.12/site-packages/flytekit/core/python_function_task.py", line 251, in compile_into_workflow
        cast(PythonFunctionWorkflow, self._wf).compile(**kwargs)
      File "/opt/micromamba/envs/runtime/lib/python3.12/site-packages/flytekit/core/workflow.py", line 846, in compile
        workflow_outputs = self._workflow_function(**input_kwargs)
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/root/fix_type.py", line 67, in wf3
        say_hello(
      File "/opt/micromamba/envs/runtime/lib/python3.12/site-packages/flytekit/core/base_task.py", line 373, in __call__
        return flyte_entity_call_handler(self, *args, **kwargs)  # type: ignore
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/opt/micromamba/envs/runtime/lib/python3.12/site-packages/flytekit/core/promise.py", line 1498, in flyte_entity_call_handler
        return create_and_link_node(ctx, entity=entity, **kwargs)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/opt/micromamba/envs/runtime/lib/python3.12/site-packages/flytekit/core/promise.py", line 1349, in create_and_link_node
        b, n = binding_from_python_std(
               ^^^^^^^^^^^^^^^^^^^^^^^^
      File "/opt/micromamba/envs/runtime/lib/python3.12/site-packages/flytekit/core/promise.py", line 997, in binding_from_python_std
        binding_data = run_sync(
                       ^^^^^^^^^
      File "/opt/micromamba/envs/runtime/lib/python3.12/site-packages/flytekit/utils/asyn.py", line 106, in run_sync
        return self._runner_map[name].run(coro)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/opt/micromamba/envs/runtime/lib/python3.12/site-packages/flytekit/utils/asyn.py", line 85, in run
        res = fut.result(None)
              ^^^^^^^^^^^^^^^^
      File "/opt/micromamba/envs/runtime/lib/python3.12/concurrent/futures/_base.py", line 456, in result
        return self.__get_result()
               ^^^^^^^^^^^^^^^^^^^
      File "/opt/micromamba/envs/runtime/lib/python3.12/concurrent/futures/_base.py", line 401, in __get_result
        raise self._exception
      File "/opt/micromamba/envs/runtime/lib/python3.12/site-packages/flytekit/core/promise.py", line 899, in binding_data_from_python_std
        raise AssertionError(
    AssertionError: Failed to Bind variable 'additional_properties' for function 'fix_type.say_hello':
     Failed to bind data [{'c': ['hello'], 'algorithm': 'xgboost'}] to any of the expected union variants.
    Value python type: list, declared python types: dict[str, float | None | str | bool | datetime.datetime | datetime.date | list[str]] | None
    Expected literal type: union_type {
      variants {
        map_value_type {
          union_type {
            variants {
              simple: FLOAT
              structure {
                tag: "float"
              }
            }
            variants {
              simple: NONE
              structure {
                tag: "none"
              }
            }
            variants {
              simple: STRING
              structure {
                tag: "str"
              }
            }
            variants {
              simple: BOOLEAN
              structure {
                tag: "bool"
              }
            }
            variants {
              simple: DATETIME
              structure {
                tag: "datetime"
              }
            }
            variants {
              simple: DATETIME
              structure {
                tag: "date"
              }
            }
            variants {
              collection_type {
                simple: STRING
              }
              structure {
                tag: "Typed List"
              }
            }
          }
        }
        structure {
          tag: "Typed Dict"
        }
      }
      variants {
        simple: NONE
        structure {
          tag: "none"
        }
      }
    }


Message:

    AssertionError: Failed to Bind variable 'additional_properties' for function 'fix_type.say_hello':
     Failed to bind data [{'c': ['hello'], 'algorithm': 'xgboost'}] to any of the expected union variants.
    Value python type: list, declared python types: dict[str, float | None | str | bool | datetime.datetime | datetime.date | list[str]] | None
    Expected literal type: union_type {
      variants {
        map_value_type {
          union_type {
            variants {
              simple: FLOAT
              structure {
                tag: "float"
              }
            }
            variants {
              simple: NONE
              structure {
                tag: "none"
              }
            }
            variants {
              simple: STRING
              structure {
                tag: "str"
              }
            }
            variants {
              simple: BOOLEAN
              structure {
                tag: "bool"
              }
            }
            variants {
              simple: DATETIME
              structure {
                tag: "datetime"
              }
            }
            variants {
              simple: DATETIME
              structure {
                tag: "date"
              }
            }
            variants {
              collection_type {
                simple: STRING
              }
              structure {
                tag: "Typed List"
              }
            }
          }
        }
        structure {
          tag: "Typed Dict"
        }
      }
      variants {
        simple: NONE
        structure {
          tag: "none"
        }
      }
    }

Check all the applicable boxes

• I updated the documentation accordingly.
• All new and existing tests passed.
• All commits are signed-off.

Related PRs

Docs link

Summary by Bito

This pull request enhances error messaging in the Flytekit library's type engine, improving clarity for user debugging of input and output bindings. Key updates include modifications to the `__repr__` method for `LiteralType`, refined error messages for incorrect inputs, and the conversion of several unit tests to async for better performance.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.38%. Comparing base (23de1ab) to head (ecb529a).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3334      +/-   ##
==========================================
- Coverage   81.16%   79.38%   -1.78%     
==========================================
  Files         215      216       +1     
  Lines       22634    22673      +39     
  Branches     2965     2969       +4     
==========================================
- Hits        18370    18000     -370     
- Misses       3434     3839     +405     
- Partials      830      834       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.