ashb commented on code in PR #65423:
URL: https://github.com/apache/airflow/pull/65423#discussion_r3219191732
##########
airflow-core/docs/index.rst:
##########
@@ -156,6 +156,7 @@ experience is continuously improving, but defining
workflows as code is central
best-practices
faq
troubleshooting
+ contributor/error_codes/index
Review Comment:
Nothing else in the docs is under contributor is it? This seems like an odd
location for it regardless.
##########
airflow-core/docs/error_mapping.yml:
##########
@@ -0,0 +1,713 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+---
+error_codes:
+ # Specify error codes below for exception classes as required.
+ # Exception class can have multiple error codes representing its respective
error states.
+ # e.g. AirflowNotFoundException can have AERR001, AERR002, etc representing
different not found cases.
+ - error_code: AERR001
+ exception_type: AirflowNotFoundException
+ user_facing_error_message: Connection not found for requested connection ID
+ description: This error occurs when Airflow is unable to locate a
connection
+ with given connection id in any configured secrets backend or metadata
+ store. It attempted to retrieve the connection, but no matching entry
was found.
+ first_steps:
+ Verify that the connection ID is correctly configured in Airflow.
+ Check your secrets backend, environment variables, or Airflow UI to
+ ensure the connection exists and is accessible to the current task.
+ Confirm there are no typos in the conn_id. If using a secrets backend,
+ ensure it is properly configured and reachable.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/howto/connection.html#using-connections
+
+ - error_code: AERR002
+ exception_type: AirflowNotFoundException
+ user_facing_error_message: Requested connection ID is not defined
+ description: This error occurs when Airflow attempts to resolve a
connection
+ using its standard secrets resolution flow (SecretCache and configured
+ secrets backends) and is unable to find any matching connection for
+ given connection ID. It also indicates that all configured backends were
+ checked sequentially but none returned a valid connection.
+ first_steps: >
+ Confirm that the connection is defined in at least one configured
+ secrets backend or in the Airflow metadata database. Check whether
+ SecretCache is enabled and populated correctly. Verify backend
+ configuration in airflow.cfg and ensure all external secrets providers
+ (e.g., AWS Secrets Manager, HashiCorp Vault) are reachable and properly
+ authenticated. Also confirm there are no typos in the conn_id and that
+ team_name (if used) matches the stored entry.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/security/secrets/secrets-backend/index.html
+
+ - error_code: AERR003
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: Provided cron expression is invalid
+ description: This error is raised when Airflow attempts to validate a cron
+ expression using croniter and the expression is malformed or represents
+ an invalid schedule. It could either be due to invalid cron syntax or
+ invalid date/time values.
+ first_steps: >
+ Verify that the cron expression follows standard cron syntax (minute,
+ hour, day of month, month, day of week). Check for invalid characters,
+ incorrect field counts, or out-of-range values (e.g., minute > 59,
+ month > 12). Test the expression using a cron validator or croniter
+ directly in a Python shell. If using presets or dynamic inputs,
+ ensure they resolve to valid cron strings.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/cron.html
+
+ - error_code: AERR004
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: Cron schedule interval must be a positive
duration
+ description: >
+ This error occurs when Airflow validates a timetable based on a time
+ duration and finds that the resulting scheduled time is not in the
+ future. Specifically, if adding the provided interval to the current
+ time does not advance time (i.e., its either now or before now), the
+ interval is considered zero or negative. This violates Airflow's
+ requirement that scheduling intervals must move forward in time.
+ first_steps: >
+ Check the value of the provided cron schedule interval and ensure it
+ represents a strictly positive duration. Verify that none of its
+ components (days, seconds, etc.) result in a zero or negative total. If
+ the interval is dynamically computed, inspect the logic to confirm it
+ cannot produce negative or zero values.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/timetable.html
+
+ - error_code: AERR005
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: Asset-based timetables cannot be nested
+ description:
+ This error occurs when Airflow validates a timetable configuration
+ and detects that an AssetTriggeredTimetable is being used inside another
+ timetable. Nested asset-driven scheduling is not supported because
+ asset-triggered timetables are designed to operate as top-level
+ scheduling constructs. Attempting to embed one within another leads to
+ ambiguous or conflicting scheduling behavior, so Airflow raises an
+ AirflowTimetableInvalid exception.
+ first_steps: >
+ Review the timetable configuration and ensure that an
+ AssetTriggeredTimetable is not being passed as a nested or inner
+ timetable. If you need multiple scheduling conditions, consider
+ restructuring the DAG to use a single asset-based timetable or separate
+ DAGs. Confirm that the timetable parameter is a supported non-asset
+ timetable type when combined with asset conditions.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/assets.html
+
+ - error_code: AERR006
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: All elements in 'assets' must be valid asset
objects
+ description: This error is raised when Airflow validates the asset
condition
+ configuration and finds that one or more elements are serialized.
+ Asset-based scheduling requires all provided assets to be properly
+ serialized asset objects so they can be tracked and evaluated by the
+ scheduler. Passing unsupported types (e.g., strings, dictionaries, or
+ uninitialized objects) causes this validation to fail.
+ first_steps: >
+ Inspect the asset contents or asset_condition input and ensure each
+ element is serializable i.e. an instance of SerializedAssetBase. If
+ assets are being dynamically constructed, verify they are properly
+ serialized before being passed. Avoid using raw identifiers or
+ unsupported data types, and instead use the appropriate Airflow asset
+ classes or serialization utilities.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/serializers.html
+
+ - error_code: AERR007
+ exception_type: TaskNotFound
+ user_facing_error_message: Requested task ID was not found in the DAG
+ description:
+ This error occurs when Airflow attempts to retrieve a task from the
+ DAG using a given task_id, but no matching entry exists in the internal
+ task_dict. It indicates that the specified task ID is either incorrect,
+ missing, or not registered as part of the DAG definition.
+ first_steps: >
+ Verify that the task_id is spelled correctly and matches exactly with
+ the task defined in the DAG (including case sensitivity). Check that the
+ task is properly instantiated and added to the DAG context. If the
+ task_id is dynamically generated, confirm the logic produces the
+ expected value. Also ensure that the DAG has been fully parsed and all
+ tasks are registered before attempting retrieval.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html
+
+ - error_code: AERR008
+ exception_type: NodeNotFound
Review Comment:
TaskNotFound is essentially the same as NodeNotFound.
##########
airflow-core/docs/error_mapping.yml:
##########
@@ -0,0 +1,713 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+---
+error_codes:
+ # Specify error codes below for exception classes as required.
+ # Exception class can have multiple error codes representing its respective
error states.
+ # e.g. AirflowNotFoundException can have AERR001, AERR002, etc representing
different not found cases.
+ - error_code: AERR001
+ exception_type: AirflowNotFoundException
+ user_facing_error_message: Connection not found for requested connection ID
+ description: This error occurs when Airflow is unable to locate a
connection
+ with given connection id in any configured secrets backend or metadata
+ store. It attempted to retrieve the connection, but no matching entry
was found.
+ first_steps:
+ Verify that the connection ID is correctly configured in Airflow.
+ Check your secrets backend, environment variables, or Airflow UI to
+ ensure the connection exists and is accessible to the current task.
+ Confirm there are no typos in the conn_id. If using a secrets backend,
+ ensure it is properly configured and reachable.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/howto/connection.html#using-connections
+
+ - error_code: AERR002
+ exception_type: AirflowNotFoundException
+ user_facing_error_message: Requested connection ID is not defined
+ description: This error occurs when Airflow attempts to resolve a
connection
+ using its standard secrets resolution flow (SecretCache and configured
+ secrets backends) and is unable to find any matching connection for
+ given connection ID. It also indicates that all configured backends were
+ checked sequentially but none returned a valid connection.
+ first_steps: >
+ Confirm that the connection is defined in at least one configured
+ secrets backend or in the Airflow metadata database. Check whether
+ SecretCache is enabled and populated correctly. Verify backend
+ configuration in airflow.cfg and ensure all external secrets providers
+ (e.g., AWS Secrets Manager, HashiCorp Vault) are reachable and properly
+ authenticated. Also confirm there are no typos in the conn_id and that
+ team_name (if used) matches the stored entry.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/security/secrets/secrets-backend/index.html
+
+ - error_code: AERR003
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: Provided cron expression is invalid
+ description: This error is raised when Airflow attempts to validate a cron
+ expression using croniter and the expression is malformed or represents
+ an invalid schedule. It could either be due to invalid cron syntax or
+ invalid date/time values.
+ first_steps: >
+ Verify that the cron expression follows standard cron syntax (minute,
+ hour, day of month, month, day of week). Check for invalid characters,
+ incorrect field counts, or out-of-range values (e.g., minute > 59,
+ month > 12). Test the expression using a cron validator or croniter
+ directly in a Python shell. If using presets or dynamic inputs,
+ ensure they resolve to valid cron strings.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/cron.html
+
+ - error_code: AERR004
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: Cron schedule interval must be a positive
duration
+ description: >
+ This error occurs when Airflow validates a timetable based on a time
+ duration and finds that the resulting scheduled time is not in the
+ future. Specifically, if adding the provided interval to the current
+ time does not advance time (i.e., its either now or before now), the
+ interval is considered zero or negative. This violates Airflow's
+ requirement that scheduling intervals must move forward in time.
+ first_steps: >
+ Check the value of the provided cron schedule interval and ensure it
+ represents a strictly positive duration. Verify that none of its
+ components (days, seconds, etc.) result in a zero or negative total. If
+ the interval is dynamically computed, inspect the logic to confirm it
+ cannot produce negative or zero values.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/timetable.html
+
+ - error_code: AERR005
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: Asset-based timetables cannot be nested
+ description:
+ This error occurs when Airflow validates a timetable configuration
+ and detects that an AssetTriggeredTimetable is being used inside another
+ timetable. Nested asset-driven scheduling is not supported because
+ asset-triggered timetables are designed to operate as top-level
+ scheduling constructs. Attempting to embed one within another leads to
+ ambiguous or conflicting scheduling behavior, so Airflow raises an
+ AirflowTimetableInvalid exception.
+ first_steps: >
+ Review the timetable configuration and ensure that an
+ AssetTriggeredTimetable is not being passed as a nested or inner
+ timetable. If you need multiple scheduling conditions, consider
+ restructuring the DAG to use a single asset-based timetable or separate
+ DAGs. Confirm that the timetable parameter is a supported non-asset
+ timetable type when combined with asset conditions.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/assets.html
+
+ - error_code: AERR006
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: All elements in 'assets' must be valid asset
objects
+ description: This error is raised when Airflow validates the asset
condition
+ configuration and finds that one or more elements are serialized.
+ Asset-based scheduling requires all provided assets to be properly
+ serialized asset objects so they can be tracked and evaluated by the
+ scheduler. Passing unsupported types (e.g., strings, dictionaries, or
+ uninitialized objects) causes this validation to fail.
+ first_steps: >
+ Inspect the asset contents or asset_condition input and ensure each
+ element is serializable i.e. an instance of SerializedAssetBase. If
+ assets are being dynamically constructed, verify they are properly
+ serialized before being passed. Avoid using raw identifiers or
+ unsupported data types, and instead use the appropriate Airflow asset
+ classes or serialization utilities.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/serializers.html
+
+ - error_code: AERR007
+ exception_type: TaskNotFound
+ user_facing_error_message: Requested task ID was not found in the DAG
+ description:
+ This error occurs when Airflow attempts to retrieve a task from the
+ DAG using a given task_id, but no matching entry exists in the internal
+ task_dict. It indicates that the specified task ID is either incorrect,
+ missing, or not registered as part of the DAG definition.
+ first_steps: >
+ Verify that the task_id is spelled correctly and matches exactly with
+ the task defined in the DAG (including case sensitivity). Check that the
+ task is properly instantiated and added to the DAG context. If the
+ task_id is dynamically generated, confirm the logic produces the
+ expected value. Also ensure that the DAG has been fully parsed and all
+ tasks are registered before attempting retrieval.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html
+
+ - error_code: AERR008
+ exception_type: NodeNotFound
+ user_facing_error_message: Requested task label was not found in the DAG
+ description:
+ This error occurs when Airflow attempts to retrieve a task from the
+ DAG using a label, but no matching entry exists in the internal
+ task_dict. It indicates that the specified task label is either
incorrect,
+ missing, or not registered as part of the DAG definition.
+ first_steps: >
+ Verify that the task label is spelled correctly and matches exactly with
+ the task defined in the DAG (including case sensitivity). Check that the
+ task is properly instantiated and added to the DAG context. If the
+ task label is dynamically generated, confirm the logic produces the
+ expected value. Also ensure that the DAG has been fully parsed and all
+ tasks are registered before attempting retrieval.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html
+
+ - error_code: AERR009
+ exception_type: DagCodeNotFound
+ user_facing_error_message: DAG source code could not be found in metadata
database
Review Comment:
Is this exposed to a user anywhere? I think it is just an internal exception
that is caught by the API server
##########
airflow-core/docs/error_mapping.yml:
##########
@@ -0,0 +1,713 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+---
+error_codes:
+ # Specify error codes below for exception classes as required.
+ # Exception class can have multiple error codes representing its respective
error states.
+ # e.g. AirflowNotFoundException can have AERR001, AERR002, etc representing
different not found cases.
+ - error_code: AERR001
+ exception_type: AirflowNotFoundException
+ user_facing_error_message: Connection not found for requested connection ID
+ description: This error occurs when Airflow is unable to locate a
connection
+ with given connection id in any configured secrets backend or metadata
+ store. It attempted to retrieve the connection, but no matching entry
was found.
+ first_steps:
+ Verify that the connection ID is correctly configured in Airflow.
+ Check your secrets backend, environment variables, or Airflow UI to
+ ensure the connection exists and is accessible to the current task.
+ Confirm there are no typos in the conn_id. If using a secrets backend,
+ ensure it is properly configured and reachable.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/howto/connection.html#using-connections
+
+ - error_code: AERR002
+ exception_type: AirflowNotFoundException
+ user_facing_error_message: Requested connection ID is not defined
+ description: This error occurs when Airflow attempts to resolve a
connection
+ using its standard secrets resolution flow (SecretCache and configured
+ secrets backends) and is unable to find any matching connection for
+ given connection ID. It also indicates that all configured backends were
+ checked sequentially but none returned a valid connection.
+ first_steps: >
+ Confirm that the connection is defined in at least one configured
+ secrets backend or in the Airflow metadata database. Check whether
+ SecretCache is enabled and populated correctly. Verify backend
+ configuration in airflow.cfg and ensure all external secrets providers
+ (e.g., AWS Secrets Manager, HashiCorp Vault) are reachable and properly
+ authenticated. Also confirm there are no typos in the conn_id and that
+ team_name (if used) matches the stored entry.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/security/secrets/secrets-backend/index.html
+
+ - error_code: AERR003
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: Provided cron expression is invalid
+ description: This error is raised when Airflow attempts to validate a cron
+ expression using croniter and the expression is malformed or represents
+ an invalid schedule. It could either be due to invalid cron syntax or
+ invalid date/time values.
+ first_steps: >
+ Verify that the cron expression follows standard cron syntax (minute,
+ hour, day of month, month, day of week). Check for invalid characters,
+ incorrect field counts, or out-of-range values (e.g., minute > 59,
+ month > 12). Test the expression using a cron validator or croniter
+ directly in a Python shell. If using presets or dynamic inputs,
+ ensure they resolve to valid cron strings.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/cron.html
+
+ - error_code: AERR004
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: Cron schedule interval must be a positive
duration
+ description: >
+ This error occurs when Airflow validates a timetable based on a time
+ duration and finds that the resulting scheduled time is not in the
+ future. Specifically, if adding the provided interval to the current
+ time does not advance time (i.e., its either now or before now), the
+ interval is considered zero or negative. This violates Airflow's
+ requirement that scheduling intervals must move forward in time.
+ first_steps: >
+ Check the value of the provided cron schedule interval and ensure it
+ represents a strictly positive duration. Verify that none of its
+ components (days, seconds, etc.) result in a zero or negative total. If
+ the interval is dynamically computed, inspect the logic to confirm it
+ cannot produce negative or zero values.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/timetable.html
+
+ - error_code: AERR005
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: Asset-based timetables cannot be nested
+ description:
+ This error occurs when Airflow validates a timetable configuration
+ and detects that an AssetTriggeredTimetable is being used inside another
+ timetable. Nested asset-driven scheduling is not supported because
+ asset-triggered timetables are designed to operate as top-level
+ scheduling constructs. Attempting to embed one within another leads to
+ ambiguous or conflicting scheduling behavior, so Airflow raises an
+ AirflowTimetableInvalid exception.
+ first_steps: >
+ Review the timetable configuration and ensure that an
+ AssetTriggeredTimetable is not being passed as a nested or inner
+ timetable. If you need multiple scheduling conditions, consider
+ restructuring the DAG to use a single asset-based timetable or separate
+ DAGs. Confirm that the timetable parameter is a supported non-asset
+ timetable type when combined with asset conditions.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/assets.html
+
+ - error_code: AERR006
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: All elements in 'assets' must be valid asset
objects
+ description: This error is raised when Airflow validates the asset
condition
+ configuration and finds that one or more elements are serialized.
+ Asset-based scheduling requires all provided assets to be properly
+ serialized asset objects so they can be tracked and evaluated by the
+ scheduler. Passing unsupported types (e.g., strings, dictionaries, or
+ uninitialized objects) causes this validation to fail.
+ first_steps: >
+ Inspect the asset contents or asset_condition input and ensure each
+ element is serializable i.e. an instance of SerializedAssetBase. If
+ assets are being dynamically constructed, verify they are properly
+ serialized before being passed. Avoid using raw identifiers or
+ unsupported data types, and instead use the appropriate Airflow asset
+ classes or serialization utilities.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/serializers.html
+
+ - error_code: AERR007
+ exception_type: TaskNotFound
+ user_facing_error_message: Requested task ID was not found in the DAG
+ description:
+ This error occurs when Airflow attempts to retrieve a task from the
+ DAG using a given task_id, but no matching entry exists in the internal
+ task_dict. It indicates that the specified task ID is either incorrect,
+ missing, or not registered as part of the DAG definition.
+ first_steps: >
+ Verify that the task_id is spelled correctly and matches exactly with
+ the task defined in the DAG (including case sensitivity). Check that the
+ task is properly instantiated and added to the DAG context. If the
+ task_id is dynamically generated, confirm the logic produces the
+ expected value. Also ensure that the DAG has been fully parsed and all
+ tasks are registered before attempting retrieval.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html
+
+ - error_code: AERR008
+ exception_type: NodeNotFound
+ user_facing_error_message: Requested task label was not found in the DAG
+ description:
+ This error occurs when Airflow attempts to retrieve a task from the
+ DAG using a label, but no matching entry exists in the internal
+ task_dict. It indicates that the specified task label is either
incorrect,
+ missing, or not registered as part of the DAG definition.
+ first_steps: >
+ Verify that the task label is spelled correctly and matches exactly with
+ the task defined in the DAG (including case sensitivity). Check that the
+ task is properly instantiated and added to the DAG context. If the
+ task label is dynamically generated, confirm the logic produces the
+ expected value. Also ensure that the DAG has been fully parsed and all
+ tasks are registered before attempting retrieval.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html
+
+ - error_code: AERR009
+ exception_type: DagCodeNotFound
+ user_facing_error_message: DAG source code could not be found in metadata
database
+ description: >
+ This error occurs when Airflow attempts to retrieve DAG source code
+ from the metadata database using a dag_id, but no matching DagCode
+ record exists. The lookup queries the latest stored DAG code entry
+ ordered by last_updated, and raises DagCodeNotFound when the query
+ returns no result. This usually indicates that the DAG has not yet
+ been serialized into the database, has been removed, or the dag_id
+ provided does not match any registered DAG code entry.
+ first_steps: >
+ Verify that the dag_id exists and matches the expected DAG exactly,
+ including case sensitivity. Confirm that the DAG file has been parsed
+ successfully by the scheduler and that DAG serialization or DAG code
+ persistence is functioning correctly. Check whether the DAG was recently
+ deleted, renamed, or excluded from parsing. Also inspect the dag_code
+ table in the Airflow metadata database to ensure the corresponding
+ source code entry is present.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/administration-and-deployment/dag-serialization.html
+
+ - error_code: AERR010
+ exception_type: DagNotFound
+ user_facing_error_message: Requested DAG could not be found
+ description: >
+ This error occurs when Airflow attempts to perform a dry run operation
+ on a DAG but cannot locate the corresponding serialized DAG definition
+ in the metadata database. The system queries the latest serialized DAG
+ record for the provided dag_id, and raises DagNotFound when no matching
+ entry exists. This typically indicates that the DAG has not been parsed,
+ has not been serialized, has been deleted, or the dag_id provided does
+ not correspond to any known DAG in the system.
+ first_steps: >
+ Verify that the dag_id is correct and matches an existing DAG definition
+ exactly, including case sensitivity. Ensure that the DAG file is present
+ in the DAGs folder and has been successfully parsed by the scheduler.
+ Confirm that DAG serialization is enabled and functioning properly, and
+ that the SerializedDagModel table contains entries for the DAG. If the
+ DAG was recently added, allow time for the scheduler to pick it up and
+ serialize it.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
+
+ - error_code: AERR011
+ exception_type: DagNotFound
+ user_facing_error_message: Requested DAG could not be found for backfill
operation
+ description: >
+ This error occurs when Airflow attempts to create a backfill job for a
+ specified DAG but cannot locate its serialized definition in the metadata
+ database. The system queries the latest serialized DAG entry using the
+ provided dag_id, and raises DagNotFound when no corresponding record is
+ found. This indicates that the DAG is missing from the serialized DAG
store,
+ has not been parsed or serialized yet, or the dag_id does not match any
+ registered DAG in the system.
+ first_steps: >
+ Verify that the dag_id is correct and matches an existing DAG definition
+ exactly, including case sensitivity. Ensure the DAG file is present in
the
+ DAGs directory and has been successfully parsed by the scheduler. Confirm
+ that DAG serialization is enabled and that entries exist in the
+ SerializedDagModel table for the given DAG. If the DAG was recently
added or
+ modified, allow time for the scheduler to process and serialize it before
+ retrying the backfill operation.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
+
+ - error_code: AERR012
+ exception_type: PoolNotFound
+ user_facing_error_message: Pool deletion failed because the pool is either
protected or does not exist
+ description: >
+ This error occurs when Airflow attempts to delete a pool but the
operation
+ cannot be completed due to one of two conditions. If the requested pool
is
+ the default pool, Airflow raises AirflowException because the default
pool
+ is a protected system resource and cannot be removed. If the specified
pool
+ name does not exist in the metadata database, PoolNotFound is raised. In
both
+ cases, the deletion process is aborted before any database modification
occurs.
+ first_steps: >
+ If the error is due to the default pool, verify that the pool name is not
+ "default_pool", as this pool is reserved and cannot be deleted. If the
error
+ indicates PoolNotFound, confirm that the pool name is spelled correctly
and
+ exists in the Airflow metadata database. You can list available pools
via the
+ Airflow CLI or UI to validate existence before attempting deletion.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/administration-and-deployment/pools.html
+
+ - error_code: AERR013
+ exception_type: DagNotFound
+ user_facing_error_message: Requested DAG could not be found for triggering
a DAG run
+ description: >
+ This error occurs when Airflow attempts to trigger a DAG run but cannot
+ locate the latest version of the specified DAG within the DagBag or
metadata
+ store. The system calls get_latest_version_of_dag(dag_id), and raises
+ DagNotFound when no matching DAG definition is found. This indicates that
+ the DAG is missing, not yet parsed, not included in the DAG bag, or the
+ dag_id does not correspond to any currently available DAG version.
+ first_steps: >
+ Verify that the dag_id is correct and matches an existing DAG definition
+ exactly, including case sensitivity. Ensure that the DAG file is present
in
+ the DAGs directory and has been successfully parsed by the scheduler.
Check
+ that the DAG is not paused or filtered out from the DagBag. If the DAG
was
+ recently added or modified, confirm that the scheduler has reloaded it
and
+ that it appears in the Airflow UI before retrying the trigger operation.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
+
+ - error_code: AERR014
+ exception_type: DagNotFound
+ user_facing_error_message: Requested DAG could not be found in the
DagModel registry
+ description: >
+ This error occurs when Airflow attempts to trigger a DAG run but cannot
+ locate the corresponding DAG entry in the DagModel table. The system
raises
+ DagNotFound when no active or registered DAG record exists for the
provided
+ dag_id. This indicates that the DAG is either not present in the
metadata database,
+ has not been parsed and registered by the scheduler, or has been removed
or renamed.
+ first_steps: >
+ Verify that the dag_id is correct and exactly matches an existing DAG
+ definition, including case sensitivity. Ensure the DAG file exists in the
+ configured DAGs folder and has been successfully parsed by the scheduler.
+ Check the Airflow UI or DagModel records in the metadata database to
+ confirm that the DAG is registered and active. If the DAG was recently
+ added or modified, allow time for scheduler parsing and metadata updates
+ before retrying the trigger operation.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
+
+ - error_code: AERR015
+ exception_type: DagNotFound
+ user_facing_error_message: DAG deletion failed because active tasks exist
or the DAG does not exist
+ description: >
+ This error occurs when Airflow attempts to delete a DAG but cannot
proceed
+ due to one of two blocking conditions. If any TaskInstance for the DAG is
+ still in the RUNNING state, an AirflowException is raised to prevent
unsafe
+ deletion while work is still executing. If no matching DagModel entry
exists
+ for the provided dag_id, DagNotFound is raised, indicating that the DAG
is
+ not registered in the metadata database. In both cases, deletion is
aborted
+ to maintain consistency between the DAG registry and task execution
state.
+ first_steps: >
+ If the error is caused by running tasks, ensure all active TaskInstances
for
+ the DAG are completed, failed, or cleared before retrying deletion. You
can
+ verify task state via the Airflow UI, CLI, or metadata database. If the
error
+ is DagNotFound, confirm that the dag_id is correct and exists in
DagModel.
+ Check whether the DAG has already been deleted, renamed, or never
registered
+ due to parsing issues. Validate DAG presence in the Airflow UI before
retrying.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
+
+ - error_code: AERR016
+ exception_type: DagNotFound
+ user_facing_error_message: DAG definition could not be found in the
serialized DAG store
+ description: >
+ This error occurs when Airflow attempts to retrieve a DAG from the
serialized
+ DAG store for a task instance execution, but no corresponding serialized
DAG
+ entry exists. The system queries the scheduler DAG bag for the DAG
associated
+ with the given dag_run, and raises DagNotFound when the serialized_dag
table
+ does not contain a matching record. This indicates that the DAG has not
been
+ serialized, is missing from the metadata database, or is unavailable to
the
+ scheduler at runtime.
+ first_steps: >
+ Verify that the dag_id exists and is correctly defined in the DAG files.
+ Ensure that the scheduler has successfully parsed and serialized the DAG.
+ Check the serialized_dag table in the metadata database to confirm that
an
+ entry exists for the given DAG. If the DAG was recently deployed or
updated,
+ allow time for the scheduler to process and serialize it. Also verify
that
+ the DAG is not excluded by DAG serialization settings or scheduler
filters.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/administration-and-deployment/dag-serialization.html
+
+ - error_code: AERR017
+ exception_type: DagRunNotFound
+ user_facing_error_message: >
+ Requested DagRun could not be found for the given run identifier or
logical date
+ description: >
+ This error occurs when Airflow attempts to retrieve a DagRun using
either a
+ run_id or logical_date, but no matching DagRun exists in the metadata
database.
+ The system first tries to resolve the identifier and if no DagRun is
found and
+ creation of a new DagRun is not allowed then a DagRunNotFound exception
is raised.
+ This indicates that the requested DAG run has not been created, has been
deleted,
+ or the provided identifier does not match any existing DagRun.
+ first_steps: >
+ Verify that the run_id or logical_date is correct and corresponds to an
existing
+ DagRun for the specified dag_id. Check the Airflow UI or DagRun table in
the
+ metadata database to confirm whether the run exists. Ensure that the
correct
+ time format is used for logical_date and that timezone handling matches
the DAG
+ configuration. If the DagRun is expected to be created automatically,
confirm
+ whether create_if_necessary is enabled in the calling context.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
+
+ - error_code: AERR018
+ exception_type: TaskInstanceNotFound
+ user_facing_error_message: Requested TaskInstance could not be found for
the given DAG run and task
+ description: >
+ This error occurs when Airflow attempts to retrieve a TaskInstance from a
+ DagRun using the provided task_id and map_index, but no matching record
exists.
+ The system calls dag_run.get_task_instance(...) to locate the task
instance,
+ and if no TaskInstance is found and creation is not permitted
+ (create_if_necessary=False), a TaskInstanceNotFound exception is raised.
+ This indicates that the TaskInstance has not been created yet, does not
exist
+ for the specified DagRun, or the provided identifiers (task_id,
map_index,
+ run_id/logical_date) do not correspond to an existing execution record.
+ first_steps: >
+ Verify that the task_id exists in the DAG definition and is correctly
spelled,
+ including case sensitivity. Ensure that the DagRun for the given run_id
or
+ logical_date exists and has been properly created. If using mapped tasks,
+ confirm that the map index is valid and corresponds to an existing mapped
+ task instance. Check the Airflow UI or TaskInstance table in the metadata
+ database to verify whether the task instance exists. If the DAG run is
new,
+ ensure that task instances have been generated before attempting
retrieval.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html
+
+ - error_code: AERR019
+ exception_type: DagRunNotFound
+ user_facing_error_message: Requested DagRun could not be found when
fetching task states
+ description: >
+ This error occurs when Airflow CLI attempts to retrieve the status of all
+ TaskInstances within a specific DagRun, but no matching DagRun exists in
the
+ metadata database. The command resolves the DagRun and raises
DagRunNotFound
+ when no corresponding DagRun is found for the given dag_id. This
indicates that
+ the requested DAG run does not exist, has been deleted, or the provided
identifier
+ does not match any stored execution record.
+ first_steps: >
+ Verify that the dag_id is correct and matches an existing DAG. Ensure
that
+ the run_id or logical_date provided corresponds to an actual DagRun,
which
+ can be confirmed via the Airflow UI or DagRun database table. Check that
the
+ correct execution date format and timezone are used for logical_date
inputs.
+ If the DagRun was recently created, ensure it has been fully registered
before
+ retrying the CLI command.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
+
+ - error_code: AERR020
+ exception_type: PoolNotFound
+ user_facing_error_message: Requested pool could not be found
+ description: >
+ This error occurs when Airflow attempts to retrieve a pool definition
+ using the provided pool name, but no matching pool exists in the metadata
+ database. Airflow raises PoolNotFound when the pool name lookup returns
no result.
+ This indicates that the specified pool has not been created, has been
deleted, or
+ the provided pool name does not exactly match any existing pool
configuration.
+ first_steps: >
+ Verify that the pool name is correct and matches an existing Airflow
pool.
+ Check the Airflow UI under Admin > Pools or query the metadata database
to
+ confirm the pool exists. Ensure there are no typographical errors, case
+ mismatches, or environment-specific configuration differences. If the
pool
+ was recently created, verify that the scheduler and webserver are using
the
+ latest metadata state before retrying the operation.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/administration-and-deployment/pools.html
+
+ - error_code: AERR021
+ exception_type: AirflowNotFoundException
+ user_facing_error_message: S3 object not found for the specified bucket
and key
+ description: >
+ This error occurs within the Apache Airflow Amazon provider when an
S3Hook attempts to retrieve
+ an object from an Amazon S3 bucket, but the specified key does not
exist. The underlying AWS
+ ClientError returns a 404 (NoSuchKey), which indicates that the object
could not be found in the
+ bucket. Airflow translates this into an AirflowNotFoundException to
signal a missing upstream
+ artifact or data dependency in the DAG workflow.
+ first_steps:
+ Verify that the S3 bucket name and object key used in the Airflow task
are correct. Check the
+ Amazon S3 console to confirm the object exists at the expected path.
Ensure upstream Airflow
+ tasks (e.g., S3 upload or data generation steps) completed successfully.
Validate that the Airflow
+ S3Hook is using the correct AWS connection configured in Airflow
Connections. Confirm that the
+ IAM role or credentials associated with the Airflow connection have
access to the bucket and object.
+ Check for environment mismatches such as dev/staging/prod bucket
configuration.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow-providers-amazon/stable/_api/airflow/providers/amazon/aws/hooks/s3/index.html
+
+ - error_code: AERR022
+ exception_type: AirflowNotFoundException
+ user_facing_error_message: Docker registry configuration is incomplete
+ description: >
+ This error occurs within the Apache Airflow Docker provider when
attempting to authenticate
+ or connect to a Docker registry but required connection parameters are
missing. Docker
+ connection (Airflow Connection object) is missing either the registry
URL or the username.
+ Since both fields are required for registry authentication, Airflow
raises an exception to
+ indicate that the Docker registry connection is not properly configured
in Airflow Connections.
+ first_steps:
+ Verify that the Airflow Docker connection (conn_id) is configured
correctly in the Airflow UI or
+ secrets backend. Ensure the 'host' field contains a valid Docker
registry URL (e.g.,
+ https://index.docker.io/v1/ or private registry URL). Ensure the 'login'
field (username) is set
+ in the connection configuration. If using a private registry, confirm
that credentials are correctly
+ stored and accessible to Airflow. Check whether the correct conn_id is
being passed to the DockerHook
+ or DockerOperator. Validate that environment-specific overrides
(dev/staging/prod) are not missing
+ required fields.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow-providers-docker/stable/_api/airflow/providers/docker/hooks/docker/index.html
+
+ - error_code: AERR023
+ exception_type: AirflowNotFoundException
+ user_facing_error_message: Ray job not found on the cluster
+ description: >
+ This error occurs in the Apache Airflow Ray provider when the Ray
operator attempts to stop a
+ job on a Ray cluster, but the specified job_id does not exist or is no
longer available. The underlying
+ Ray client raises a NotFound exception, indicating that the job could
not be located on the cluster.
+ Airflow converts this into an AirflowNotFoundException to indicate that
the requested Ray job is
+ missing or has already completed, been removed, or is not recognized by
the cluster.
+ first_steps:
+ Verify that the job_id corresponds to an existing Ray job submission on
the target cluster.
+ Check the Ray dashboard to confirm whether the job is still running or
already completed.
+ Ensure the cluster_address points to the correct Ray cluster environment.
+ Confirm that the job was not already stopped or cleaned up by another
operator or retention policy.
+ Validate that the DAG is not using an outdated or incorrect job_id
reference.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow-providers-google/stable/operators/cloud/ray.html
+
+ - error_code: AERR024
+ exception_type: AirflowNotFoundException
+ user_facing_error_message: Google Ads link not found for the specified
property
Review Comment:
This is specific to a provider so should not be in the main list
##########
airflow-core/docs/error_mapping.yml:
##########
@@ -0,0 +1,713 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+---
+error_codes:
+ # Specify error codes below for exception classes as required.
+ # Exception class can have multiple error codes representing its respective
error states.
+ # e.g. AirflowNotFoundException can have AERR001, AERR002, etc representing
different not found cases.
+ - error_code: AERR001
+ exception_type: AirflowNotFoundException
+ user_facing_error_message: Connection not found for requested connection ID
+ description: This error occurs when Airflow is unable to locate a
connection
+ with given connection id in any configured secrets backend or metadata
+ store. It attempted to retrieve the connection, but no matching entry
was found.
+ first_steps:
+ Verify that the connection ID is correctly configured in Airflow.
+ Check your secrets backend, environment variables, or Airflow UI to
+ ensure the connection exists and is accessible to the current task.
+ Confirm there are no typos in the conn_id. If using a secrets backend,
+ ensure it is properly configured and reachable.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/howto/connection.html#using-connections
+
+ - error_code: AERR002
+ exception_type: AirflowNotFoundException
+ user_facing_error_message: Requested connection ID is not defined
+ description: This error occurs when Airflow attempts to resolve a
connection
+ using its standard secrets resolution flow (SecretCache and configured
+ secrets backends) and is unable to find any matching connection for
+ given connection ID. It also indicates that all configured backends were
+ checked sequentially but none returned a valid connection.
+ first_steps: >
+ Confirm that the connection is defined in at least one configured
+ secrets backend or in the Airflow metadata database. Check whether
+ SecretCache is enabled and populated correctly. Verify backend
+ configuration in airflow.cfg and ensure all external secrets providers
+ (e.g., AWS Secrets Manager, HashiCorp Vault) are reachable and properly
+ authenticated. Also confirm there are no typos in the conn_id and that
+ team_name (if used) matches the stored entry.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/security/secrets/secrets-backend/index.html
+
+ - error_code: AERR003
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: Provided cron expression is invalid
+ description: This error is raised when Airflow attempts to validate a cron
+ expression using croniter and the expression is malformed or represents
+ an invalid schedule. It could either be due to invalid cron syntax or
+ invalid date/time values.
+ first_steps: >
+ Verify that the cron expression follows standard cron syntax (minute,
+ hour, day of month, month, day of week). Check for invalid characters,
+ incorrect field counts, or out-of-range values (e.g., minute > 59,
+ month > 12). Test the expression using a cron validator or croniter
+ directly in a Python shell. If using presets or dynamic inputs,
+ ensure they resolve to valid cron strings.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/cron.html
+
+ - error_code: AERR004
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: Cron schedule interval must be a positive
duration
+ description: >
+ This error occurs when Airflow validates a timetable based on a time
+ duration and finds that the resulting scheduled time is not in the
+ future. Specifically, if adding the provided interval to the current
+ time does not advance time (i.e., its either now or before now), the
+ interval is considered zero or negative. This violates Airflow's
+ requirement that scheduling intervals must move forward in time.
+ first_steps: >
+ Check the value of the provided cron schedule interval and ensure it
+ represents a strictly positive duration. Verify that none of its
+ components (days, seconds, etc.) result in a zero or negative total. If
+ the interval is dynamically computed, inspect the logic to confirm it
+ cannot produce negative or zero values.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/timetable.html
+
+ - error_code: AERR005
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: Asset-based timetables cannot be nested
+ description:
+ This error occurs when Airflow validates a timetable configuration
+ and detects that an AssetTriggeredTimetable is being used inside another
+ timetable. Nested asset-driven scheduling is not supported because
+ asset-triggered timetables are designed to operate as top-level
+ scheduling constructs. Attempting to embed one within another leads to
+ ambiguous or conflicting scheduling behavior, so Airflow raises an
+ AirflowTimetableInvalid exception.
+ first_steps: >
+ Review the timetable configuration and ensure that an
+ AssetTriggeredTimetable is not being passed as a nested or inner
+ timetable. If you need multiple scheduling conditions, consider
+ restructuring the DAG to use a single asset-based timetable or separate
+ DAGs. Confirm that the timetable parameter is a supported non-asset
+ timetable type when combined with asset conditions.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/assets.html
+
+ - error_code: AERR006
+ exception_type: AirflowTimetableInvalid
+ user_facing_error_message: All elements in 'assets' must be valid asset
objects
+ description: This error is raised when Airflow validates the asset
condition
+ configuration and finds that one or more elements are serialized.
+ Asset-based scheduling requires all provided assets to be properly
+ serialized asset objects so they can be tracked and evaluated by the
+ scheduler. Passing unsupported types (e.g., strings, dictionaries, or
+ uninitialized objects) causes this validation to fail.
+ first_steps: >
+ Inspect the asset contents or asset_condition input and ensure each
+ element is serializable i.e. an instance of SerializedAssetBase. If
+ assets are being dynamically constructed, verify they are properly
+ serialized before being passed. Avoid using raw identifiers or
+ unsupported data types, and instead use the appropriate Airflow asset
+ classes or serialization utilities.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/serializers.html
+
+ - error_code: AERR007
+ exception_type: TaskNotFound
+ user_facing_error_message: Requested task ID was not found in the DAG
+ description:
+ This error occurs when Airflow attempts to retrieve a task from the
+ DAG using a given task_id, but no matching entry exists in the internal
+ task_dict. It indicates that the specified task ID is either incorrect,
+ missing, or not registered as part of the DAG definition.
+ first_steps: >
+ Verify that the task_id is spelled correctly and matches exactly with
+ the task defined in the DAG (including case sensitivity). Check that the
+ task is properly instantiated and added to the DAG context. If the
+ task_id is dynamically generated, confirm the logic produces the
+ expected value. Also ensure that the DAG has been fully parsed and all
+ tasks are registered before attempting retrieval.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html
+
+ - error_code: AERR008
+ exception_type: NodeNotFound
+ user_facing_error_message: Requested task label was not found in the DAG
+ description:
+ This error occurs when Airflow attempts to retrieve a task from the
+ DAG using a label, but no matching entry exists in the internal
+ task_dict. It indicates that the specified task label is either
incorrect,
+ missing, or not registered as part of the DAG definition.
+ first_steps: >
+ Verify that the task label is spelled correctly and matches exactly with
+ the task defined in the DAG (including case sensitivity). Check that the
+ task is properly instantiated and added to the DAG context. If the
+ task label is dynamically generated, confirm the logic produces the
+ expected value. Also ensure that the DAG has been fully parsed and all
+ tasks are registered before attempting retrieval.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html
+
+ - error_code: AERR009
+ exception_type: DagCodeNotFound
+ user_facing_error_message: DAG source code could not be found in metadata
database
+ description: >
+ This error occurs when Airflow attempts to retrieve DAG source code
+ from the metadata database using a dag_id, but no matching DagCode
+ record exists. The lookup queries the latest stored DAG code entry
+ ordered by last_updated, and raises DagCodeNotFound when the query
+ returns no result. This usually indicates that the DAG has not yet
+ been serialized into the database, has been removed, or the dag_id
+ provided does not match any registered DAG code entry.
+ first_steps: >
+ Verify that the dag_id exists and matches the expected DAG exactly,
+ including case sensitivity. Confirm that the DAG file has been parsed
+ successfully by the scheduler and that DAG serialization or DAG code
+ persistence is functioning correctly. Check whether the DAG was recently
+ deleted, renamed, or excluded from parsing. Also inspect the dag_code
+ table in the Airflow metadata database to ensure the corresponding
+ source code entry is present.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/administration-and-deployment/dag-serialization.html
+
+ - error_code: AERR010
+ exception_type: DagNotFound
+ user_facing_error_message: Requested DAG could not be found
+ description: >
+ This error occurs when Airflow attempts to perform a dry run operation
+ on a DAG but cannot locate the corresponding serialized DAG definition
+ in the metadata database. The system queries the latest serialized DAG
+ record for the provided dag_id, and raises DagNotFound when no matching
+ entry exists. This typically indicates that the DAG has not been parsed,
+ has not been serialized, has been deleted, or the dag_id provided does
+ not correspond to any known DAG in the system.
+ first_steps: >
+ Verify that the dag_id is correct and matches an existing DAG definition
+ exactly, including case sensitivity. Ensure that the DAG file is present
+ in the DAGs folder and has been successfully parsed by the scheduler.
+ Confirm that DAG serialization is enabled and functioning properly, and
+ that the SerializedDagModel table contains entries for the DAG. If the
+ DAG was recently added, allow time for the scheduler to pick it up and
+ serialize it.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
+
+ - error_code: AERR011
+ exception_type: DagNotFound
+ user_facing_error_message: Requested DAG could not be found for backfill
operation
+ description: >
+ This error occurs when Airflow attempts to create a backfill job for a
+ specified DAG but cannot locate its serialized definition in the metadata
+ database. The system queries the latest serialized DAG entry using the
+ provided dag_id, and raises DagNotFound when no corresponding record is
+ found. This indicates that the DAG is missing from the serialized DAG
store,
+ has not been parsed or serialized yet, or the dag_id does not match any
+ registered DAG in the system.
+ first_steps: >
+ Verify that the dag_id is correct and matches an existing DAG definition
+ exactly, including case sensitivity. Ensure the DAG file is present in
the
+ DAGs directory and has been successfully parsed by the scheduler. Confirm
+ that DAG serialization is enabled and that entries exist in the
+ SerializedDagModel table for the given DAG. If the DAG was recently
added or
+ modified, allow time for the scheduler to process and serialize it before
+ retrying the backfill operation.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
+
+ - error_code: AERR012
+ exception_type: PoolNotFound
+ user_facing_error_message: Pool deletion failed because the pool is either
protected or does not exist
+ description: >
+ This error occurs when Airflow attempts to delete a pool but the
operation
+ cannot be completed due to one of two conditions. If the requested pool
is
+ the default pool, Airflow raises AirflowException because the default
pool
+ is a protected system resource and cannot be removed. If the specified
pool
+ name does not exist in the metadata database, PoolNotFound is raised. In
both
+ cases, the deletion process is aborted before any database modification
occurs.
+ first_steps: >
+ If the error is due to the default pool, verify that the pool name is not
+ "default_pool", as this pool is reserved and cannot be deleted. If the
error
+ indicates PoolNotFound, confirm that the pool name is spelled correctly
and
+ exists in the Airflow metadata database. You can list available pools
via the
+ Airflow CLI or UI to validate existence before attempting deletion.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/administration-and-deployment/pools.html
+
+ - error_code: AERR013
+ exception_type: DagNotFound
+ user_facing_error_message: Requested DAG could not be found for triggering
a DAG run
+ description: >
+ This error occurs when Airflow attempts to trigger a DAG run but cannot
+ locate the latest version of the specified DAG within the DagBag or
metadata
+ store. The system calls get_latest_version_of_dag(dag_id), and raises
+ DagNotFound when no matching DAG definition is found. This indicates that
+ the DAG is missing, not yet parsed, not included in the DAG bag, or the
+ dag_id does not correspond to any currently available DAG version.
+ first_steps: >
+ Verify that the dag_id is correct and matches an existing DAG definition
+ exactly, including case sensitivity. Ensure that the DAG file is present
in
+ the DAGs directory and has been successfully parsed by the scheduler.
Check
+ that the DAG is not paused or filtered out from the DagBag. If the DAG
was
+ recently added or modified, confirm that the scheduler has reloaded it
and
+ that it appears in the Airflow UI before retrying the trigger operation.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
+
+ - error_code: AERR014
+ exception_type: DagNotFound
+ user_facing_error_message: Requested DAG could not be found in the
DagModel registry
+ description: >
+ This error occurs when Airflow attempts to trigger a DAG run but cannot
+ locate the corresponding DAG entry in the DagModel table. The system
raises
+ DagNotFound when no active or registered DAG record exists for the
provided
+ dag_id. This indicates that the DAG is either not present in the
metadata database,
+ has not been parsed and registered by the scheduler, or has been removed
or renamed.
+ first_steps: >
+ Verify that the dag_id is correct and exactly matches an existing DAG
+ definition, including case sensitivity. Ensure the DAG file exists in the
+ configured DAGs folder and has been successfully parsed by the scheduler.
+ Check the Airflow UI or DagModel records in the metadata database to
+ confirm that the DAG is registered and active. If the DAG was recently
+ added or modified, allow time for scheduler parsing and metadata updates
+ before retrying the trigger operation.
+ documentation: >
+
https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
+
+ - error_code: AERR015
+ exception_type: DagNotFound
+ user_facing_error_message: DAG deletion failed because active tasks exist
or the DAG does not exist
Review Comment:
If we're having error codes, we should have two different error codes here
as the description/steps for each is different.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
