SDK - Run deployment fails unless flow imported

[Chris-Perkins]

Bug summary

Prefect fails to execute run_deployment if flow is not imported. The following pydantic error is raised:
State is not fully defined; you should define all referenced types, then call State.model_rebuild()

This code fails:

from prefect.deployments import run_deployment

run_deployment(name="<Deployment Name>", timeout=0)

But this code succeeds:

from prefect.deployments import run_deployment
from prefect import flow # NEW!

run_deployment(name="<Deployment Name>", timeout=0)

Version info

Version:             3.1.4
API version:         0.8.4
Python version:      3.11.4
Git commit:          78ee41cb
Built:               Wed, Nov 20, 2024 7:37 PM
OS/Arch:             darwin/arm64
Profile:             default
Server type:         cloud
Pydantic version:    2.10.1

Additional context

  File "/Users/nepperkins/Desktop/arnold/jobs/file.py", line 249, in <module>
    run_deployment(name=f"<My Deployment>", timeout=0)
  File "/Users/nepperkins/.pyenv/versions/arnold/lib/python3.11/site-packages/prefect/utilities/asyncutils.py", line 399, in coroutine_wrapper
    return run_coro_as_sync(ctx_call())
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nepperkins/.pyenv/versions/arnold/lib/python3.11/site-packages/prefect/utilities/asyncutils.py", line 243, in run_coro_as_sync
    return call.result()
           ^^^^^^^^^^^^^
  File "/Users/nepperkins/.pyenv/versions/arnold/lib/python3.11/site-packages/prefect/_internal/concurrency/calls.py", line 312, in result
    return self.future.result(timeout=timeout)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nepperkins/.pyenv/versions/arnold/lib/python3.11/site-packages/prefect/_internal/concurrency/calls.py", line 182, in result
    return self.__get_result()
           ^^^^^^^^^^^^^^^^^^^
  File "/Users/nepperkins/.pyenv/versions/3.11.4/lib/python3.11/concurrent/futures/_base.py", line 401, in __get_result
    raise self._exception
  File "/Users/nepperkins/.pyenv/versions/arnold/lib/python3.11/site-packages/prefect/_internal/concurrency/calls.py", line 383, in _run_async
    result = await coro
             ^^^^^^^^^^
  File "/Users/nepperkins/.pyenv/versions/arnold/lib/python3.11/site-packages/prefect/utilities/asyncutils.py", line 225, in coroutine_wrapper
    return await task
           ^^^^^^^^^^
  File "/Users/nepperkins/.pyenv/versions/arnold/lib/python3.11/site-packages/prefect/utilities/asyncutils.py", line 389, in ctx_call
    result = await async_fn(*args, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nepperkins/.pyenv/versions/arnold/lib/python3.11/site-packages/prefect/client/utilities.py", line 103, in with_injected_client
    return await fn(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nepperkins/.pyenv/versions/arnold/lib/python3.11/site-packages/prefect/deployments/flow_runs.py", line 164, in run_deployment
    state=Scheduled(scheduled_time=scheduled_time),
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nepperkins/.pyenv/versions/arnold/lib/python3.11/site-packages/prefect/states.py", line 609, in Scheduled
    return cls(type=StateType.SCHEDULED, state_details=state_details, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nepperkins/.pyenv/versions/arnold/lib/python3.11/site-packages/pydantic/main.py", line 214, in __init__
    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nepperkins/.pyenv/versions/arnold/lib/python3.11/site-packages/pydantic/_internal/_mock_val_ser.py", line 100, in __getattr__
    raise PydanticUserError(self._error_message, code=self._code)
pydantic.errors.PydanticUserError: `State` is not fully defined; you should define all referenced types, then call `State.model_rebuild()`.

For further information visit https://errors.pydantic.dev/2.10/u/class-not-fully-defined

[desertaxle]

Thanks for the issue @Chris-Perkins! This issue has the same root cause as #15957, so I'm going to close this as a duplicate, and you can follow #15957 for updates as we work on this issue.

One other option that might feel a little less janky is to import prefect.main like this:

from prefect.deployments import run_deployment
from prefect.main

run_deployment(name="<Deployment Name>", timeout=0)

We defer building models to speed up import time, but that means that the main module needs to run to avoid errors like this. We have some circular imports that we need to detangle, but once we do, this should be relatively simple to fix.