> Error code to be derived automatically from exception class name e.g. > AirflowNotFoundException -> AERR-NOT-FOUND
To me this extra “code” is pointless. If the exception class is already unique enough, _that_ is the code, and we don’t need the same thing expressed in another form. Also with the way our code is structured, it’s possible we’ll want the “dag not found exception” in to unrelated code bases - Airflow Core and Airflow Task SDK, and while we can share code between them, I don’t think exceptions are right for this. Further, custom exception classes, and even error codes should only be used where the error might be logged, or when _user code_ might catch it. So for example, the model layer raising DagNotFound, but every caller within apache-airflow-core catches that, then it doesn’t need a code. However there are also two things I don’t like about this latest direction: 1. It encourages lots of single use exception classes, which is not a problem by itself, it just feels like bad form to me to have to define an exception to throw it from exactly one place. 2. It goes back on the direction we have been heading of getting _rid_ of things using or raising AirflowException. Assuming that the codes are for human/AI consumption then we could go with: ```python raise RuntimeException(“Something went wrong. Code: abc”) ``` -ash > On 16 May 2026, at 19:33, Omkar P <[email protected]> wrote: > > 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. >>> >> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
