This usually happens when the type annotation is evaluated but

Dict

isn’t available in the module’s runtime globals. In Prefect 3.x, flow parameters are validated (via Pydantic v2) by resolving your annotations. If you annotate a parameter as

Dict[...]

but never import

Dict

, or your imports are behind

if TYPE_CHECKING:

or affected by

from __future__ import annotations

, Prefect can hit a NameError while resolving the type. Quick ways to fix it - Prefer built-in types on Python 3.9+: use

dict[...]

instead of

typing.Dict[...]

- Or explicitly import/qualify it: -

from typing import Dict, Any

and keep

Dict[str, Any]

- or use

typing.Dict[str, Any]

(with

import typing

) - Don’t put the

typing

import behind `if TYPE_CHECKING:`; Prefect resolves types at runtime - If you’re using

from __future__ import annotations

(or on 3.11+ where annotations are stringified), make sure the names used in annotations exist in the module’s globals (import

typing

or use built-ins like

dict[...]

) Recommended patterns - Use built-in dict typing

from prefect import flow
from typing import Any

@flow
def my_flow(cfg: dict[str, Any]):
    ...

- Or use Mapping when you don’t need mutability

from prefect import flow
from collections.abc import Mapping
from typing import Any

@flow
def my_flow(cfg: Mapping[str, Any]):
    ...

- Or define a structured config with Pydantic (works well with Prefect 3.x)

from prefect import flow
from pydantic import BaseModel

class Config(BaseModel):
    retries: int
    flags: dict[str, bool] = {}

@flow
def my_flow(cfg: Config):
    ...

Notes - Ensure your parameter values are JSON-serializable when sent from the UI/API. - In notebooks or deployments, make sure the module that defines the flow imports what it needs at runtime (running an earlier cell that imported

Dict

isn’t sufficient if the flow is re-imported in a fresh process). - Avoid mixing Pydantic v1 and v2 types. If you share your flow signature (the function definition) and any

from __future__ import ...

or

typing

import lines, I can pinpoint the minimal change needed. References - Prefect source (flows): prefect/src/prefect/flows.py - Background on Pydantic validation: What is Pydantic? (blog)