Hi team, Thanks again for your inputs.
As per current consensus here, design changes finalized so far are: 1. Exceptions should have error code embedded inside them 2. Error code to Exception is to be a 1:1 mapping 3. Error code to be derived automatically from exception class name e.g. AirflowNotFoundException -> AERR-NOT-FOUND 4. YAML mapping to be removed as 1 to 3 above simplifies design 5. Exception types the user will never see (e.g. DagCodeNotFound) also to be included for error codes 6. Error meta properties like description, first_steps, etc. to be part of the exception class based on which we'll generate the doc pages Based on above points, I've updated the PR #65423, with which we can of course continue iterating over the design as the discussion progresses here. @PhilippeGagnon - with ref to your question, I suppose Jarek has covered almost everything. Couple things to add - our aim with error codes is to give more insights into exceptions raised by providing the user with more info about the error via docs. It'll sort of act as an error communication bridge between Airflow devs and Dag users. Also, error codes being context-specific and deterministic by nature compared to exception names or stack traces, will help folks reduce token usage when using LLMs...saving costs. @AndréAhlert - 1. nice idea, could you give an example of a breaking change policy? 2. we could keep these error meta properties (first_steps, user_facing_message, etc.) in the exception class to maintain a single source of truth and resolve i18n at runtime (e.g. first_steps defined in lang a, b, c. At runtime, dynamically return first_steps['b'] if locale=='b' and so on). But I'm guessing i18n will need a separate discussion thread of its own. Regards, Omkar On Wed, May 13, 2026 at 8:37 PM André Ahlert <[email protected]> wrote: > Hello everyone. > > agree with the consensus. > > On the naming question, where Jarek said he had no opinion, I'd push for > deriving the code from the MRO instead of inventing a separate component > taxonomy. > > Concretely: walk up to AirflowException, strip the "Airflow" prefix and the > "Exception" suffix, concat kebab segments root-down. > > DagNotFoundException(AirflowNotFoundException) -> > AERR-NOT-FOUND-DAG > TaskInstanceNotFoundException(AirflowNotFoundException)-> > AERR-NOT-FOUND-TASK-INSTANCE > AirflowTimetableInvalid(AirflowException) -> > AERR-TIMETABLE-INVALID > > The nice side effect is that grouping comes from the class tree for > free. except > AirflowNotFoundException already catches every AERR-NOT-FOUND-*; you don't > need a parallel AERR/SCHED/DAG/NOTFOUND scheme, the Python hierarchy is > already doing that work and just becomes visible in the string. > > btw, Two "extra" things I'd want pinned down before this lands: > 1. breaking-change policy when a class gets renamed, since the code mutates > with it > 2. where the USER_FACING_MESSAGE strings end up the day we want i18n > > Regards, > André Ahlert > > Em qua., 13 de mai. de 2026 às 09:19, Jarek Potiuk <[email protected]> > escreveu: > > > > What is the benefit of this approach over narrower exception classes? > > > > > > > Let me answer it here and provide more data: > > > > * Original discussion here: > > https://lists.apache.org/thread/k3dxc6lmrwvqgmvjr9x53poswwpoo5o8 (It > > started when we had Airflow 3 development in full swing and deferred it > to > > "after" - I guess this is the "after" :) > > * Original issue describing it - with some discussion > > https://github.com/apache/airflow/issues/43171 > > > > Quoting from that issue: > > > > Goals for this issue are the following: > > > > > > - Identify and revise error messages that are vague, lack context, or > do > > not provide clear guidance on resolving issues. > > - Provide detailed information, context, and actionable steps within > the > > error messages to help users troubleshoot. > > - Transform error messages with meaningful linking wherever possible. > > e.g. an error like Celery command failed on host can be transformed or > > displayed with something like "Please check your DAG processor timeout > > variable for this". So the user has a starting point to start > debugging. > > > > I will let Omar go into more detail, but I think the result of those > > discussions was that more precise exceptions with actionable descriptions > > can be achieved through more "fine-grained" exceptions, > > > > This is at least my own recollection of the discussion and its current > > state. Or maybe that alone will be enough, Philippe, to answer the > > question. > > > > The discussion happened a long time ago during the Airflow 3 frenzy, so > > it's no wonder we all don't remember it. Luckily, our archives remember > > everything - this is the great benefit of "if it did not happen on > devlist, > > it did not happen". > > > > J. > > >
