Hi Shahar, Thanks for starting this discussion.
I think that the second proposal is the right call. Per-package migration bundled into a breaking release is clean, the change is reviewable in one PR, and providers being independently versioned means we can move at different cadences without blocking core Airflow releases. One thing to make note of here is that the new provider specific exceptions should inherit from AirflowException during the migration window. Without that, packages that have already migrated silently break users on older catch clauses. With inheritance, the migration is incremental and safe across packages. I do not think that the first proposal would hold up. The DeprecationWarning fires at the raise site (inside provider code), not at the catch site (ie: user callbacks, execute() methods). Users who `except AirflowException` never really see it. It also floods logs with warnings from every internal exception raise users do not / should not care about. Also worth noting that the breaking surface is wider than just callbacks. Users catch AirflowException inside execute() and @task functions too. And AirflowSkipException, AirflowRescheduleException etc. are protocol exceptions that the task runner catches to drive state transitions. Those need their own explicit deprecation cycle, separate from the general provider exception migration. Thanks & Regards, Amogh Desai On Sat, May 30, 2026 at 3:28 PM Shahar Epstein <[email protected]> wrote: > Hi all, > > This follows up on the earlier lazy-consensus > <https://lists.apache.org/thread/m86gs4mqt8hq1n26g0pp0fq5h5g0x2q9> and > related discussions around deprecating AirflowException. > > While working on a cleanup PR for the Google Cloud Run operator in the > Google provider (#67769), Amogh pointed out that replacing AirflowException > with built-in or custom exceptions is a breaking change. Users may rely on > AirflowException in callbacks (on_failure_callback, on_retry_callback) or > in custom wrappers that catch it explicitly. > > Rather than making these changes incrementally across individual PRs, I'd > like to discuss a coordinated migration strategy. > Proposal > > *1. Emit a deprecation warning from **AirflowException.__init__**.* > > Although emitting warnings when exceptions are raised is uncommon, it is > justified here because users may depend on AirflowException in callbacks > and exception handlers. This provides advance notice before > package-specific migrations occur. > > *2. Migrate per package in the next breaking release of that package.* > > Require a single migration PR per package (airflow-core and each provider), > rather than spreading exception changes across multiple PRs and releases. > The migration would be included in that package's next breaking release and > documented accordingly. > Questions > > - Should we add a deprecation warning to AirflowException? > - Is the per-package migration approach reasonable? > - Should we define a project-wide exception taxonomy, or leave exception > choices to individual provider teams? > > If there's agreement, I'll follow up with a lazy-consensus proposal. > > Thanks, > > > Shahar >
