Update Airflow troubleshooting DAG to latest version - #39387
Open
charlesmyu wants to merge 5 commits into
Open
Conversation
Replace the embedded OpenLineage validation DAG code with the latest version, which restructures the validation flow: - Replace is_disabled with provider_active + inactive_reason to distinguish explicitly disabled from no-transport-config - Gate live checks (transport, network, listener) behind provider being active; skip them as a group when inactive - Short-circuit all remaining checks when the package is not installed - Move configuration conflicts check before live transport checks - Add _check_connection_transport for Airflow connection validation - Expand Datadog domain list (ap2, uk1) - Include Airflow connection conn_id in conflict detection - Make console transport and network connectivity failures critical Update the 'Understand the output' section to reflect the new output format: reordered healthy example, split provider-disabled into two rows, replace 'No transport configured' with 'Failed to resolve active transport', add non-Datadog endpoint warning row, update listener row to cover zero/multiple listeners, and note that package failure skips all subsequent checks.
Remove datad0g.com and datad0g.eu from the Datadog domain list in _is_datadog_url(). These are staging domains that should not appear in customer-facing documentation.
Remove the log.error line printing 'All subsequent checks were skipped.' from generate_validation_summary() and the corresponding text from the failure table Cause column.
charlesmyu
marked this pull request as ready for review
August 21, 2026 13:00
mobuchowski
approved these changes
Aug 21, 2026
maxvp
requested changes
Aug 21, 2026
maxvp
left a comment
maxvp
left a comment
Contributor
There was a problem hiding this comment.
Content review of the "Understand the output" section and the DAG's user-visible log output. The restructured summary reads well and the new failure-table rows map cleanly onto the new output. A few things to resolve before merge:
The legend documents three symbols, but the new summary emits a fourth. The legend in Validation summary still reads "Each line starts with one of three symbols," while the new logic emits --prefixed lines for skipped checks:
- Live transport: N/A (provider not active - fix provider status first)
- Network: N/A (provider not active - fix provider status first)
- Listener: N/A (provider not active - fix provider status first)
A reader whose provider is inactive sees three lines the page doesn't account for. Consider adding a fourth bullet:
-: Check skipped (a prerequisite check failed).
Terminology drift with the unchanged part of the page. The "The DAG checks the following" table still describes this check as Enabled state - "OpenLineage is not disabled by environment variable or Airflow config." Now that the summary output and failure table use provider is active / not active, the page names the same check two different ways. Worth updating that row to match.
The rest is inline. One note: the guides/user.html Airflow link 404s (verified with curl) - it's pre-existing text, but since the line is touched in this PR it's a good chance to fix it.
FYI for next time, not a blocker for this PR: naming branches in the form name/title (for example, charlesmyu/update-airflow-troubleshooting-dag) lets the build preview run, which makes it much easier for the docs team to review changes against a rendered page.
| # No explicit flag — provider is inactive because no transport config was found | ||
| log.error( | ||
| "OpenLineage provider is not active: no transport configuration was found. " | ||
| "Please refer to https://airflow.apache.org/docs/apache-airflow-providers-openlineage/stable/guides/user.html" |
Contributor
There was a problem hiding this comment.
Suggested change
| "Please refer to https://airflow.apache.org/docs/apache-airflow-providers-openlineage/stable/guides/user.html" | |
| "See https://airflow.apache.org/docs/apache-airflow-providers-openlineage/stable/configurations-ref.html" |
This URL 404s - guides/user.html no longer exists on the Airflow docs site. configurations-ref.html returns 200 and covers transport configuration.
| @@ -883,11 +950,13 @@ Use this table to resolve common failures: | |||
| | Log message | Cause | Resolution | | |||
| |---|---|---| | |||
| | `✗ OpenLineage not installed properly` | The OpenLineage package is missing or corrupted. | Confirm `apache-airflow-providers-openlineage` is included in your Airflow installation. For Amazon MWAA, see [Upgrade OpenLineage provider on Amazon MWAA][3]. | | |||
Contributor
There was a problem hiding this comment.
Suggested change
| | `✗ OpenLineage not installed properly` | The OpenLineage package is missing or corrupted. | Confirm `apache-airflow-providers-openlineage` is included in your Airflow installation. For Amazon MWAA, see [Upgrade OpenLineage provider on Amazon MWAA][3]. | | |
| | `✗ OpenLineage not installed properly` | The OpenLineage package is missing or corrupted. All remaining checks are skipped. | Confirm `apache-airflow-providers-openlineage` is included in your Airflow installation. For Amazon MWAA, see [Upgrade OpenLineage provider on Amazon MWAA][3]. | |
The PR description lists this row as updated to note that subsequent checks were skipped, but it's unchanged. Now that the DAG short-circuits and returns early, a reader sees a near-empty summary and could read the absent checks as passing.
| | `✗ OpenLineage is disabled` | `AIRFLOW__OPENLINEAGE__DISABLED=true` or `OPENLINEAGE_DISABLED=true` is set, or required transport configuration is missing. | Remove or set the disable variable to `false`, and verify that the transport is configured properly. | | ||
| | `✗ OpenLineage listener is not accessible` | The provider plugin cannot be imported. | Confirm the package is installed on **both scheduler and worker** pods/processes. | | ||
| | `✗ No transport configured` | No transport environment variables are set. | Follow the [Airflow setup guide][2] to configure a transport. | | ||
| | `✗ OpenLineage provider is turned off` | The provider is explicitly disabled by `AIRFLOW__OPENLINEAGE__DISABLED`, `OPENLINEAGE_DISABLED`, or `openlineage.disabled` in airflow.cfg. | Remove or set the disable variable to `false`. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `✗ OpenLineage provider is turned off` | The provider is explicitly disabled by `AIRFLOW__OPENLINEAGE__DISABLED`, `OPENLINEAGE_DISABLED`, or `openlineage.disabled` in airflow.cfg. | Remove or set the disable variable to `false`. | | |
| | `✗ OpenLineage provider is turned off` | The provider is explicitly disabled by `AIRFLOW__OPENLINEAGE__DISABLED`, `OPENLINEAGE_DISABLED`, or `openlineage.disabled` in `airflow.cfg`. | Remove the setting, or set it to `false`. | |
airflow.cfg is a filename and needs code font to match the backticked values beside it. "The disable variable" also has no clear antecedent - one of the three sources listed is a config setting, not a variable.
| | `✗ OpenLineage listener is not accessible` | The provider plugin cannot be imported. | Confirm the package is installed on **both scheduler and worker** pods/processes. | | ||
| | `✗ No transport configured` | No transport environment variables are set. | Follow the [Airflow setup guide][2] to configure a transport. | | ||
| | `✗ OpenLineage provider is turned off` | The provider is explicitly disabled by `AIRFLOW__OPENLINEAGE__DISABLED`, `OPENLINEAGE_DISABLED`, or `openlineage.disabled` in airflow.cfg. | Remove or set the disable variable to `false`. | | ||
| | `✗ OpenLineage provider is not active (no transport configuration found)` | No transport configuration was found. | Follow the [Airflow setup guide][2] to configure a transport. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `✗ OpenLineage provider is not active (no transport configuration found)` | No transport configuration was found. | Follow the [Airflow setup guide][2] to configure a transport. | | |
| | `✗ OpenLineage provider is not active (no transport configuration found)` | The provider deactivates itself when no transport configuration is present, even though nothing explicitly disabled it. | Follow the [Airflow setup guide][2] to configure a transport. | |
The Cause column currently restates the log message verbatim. Explaining the mechanism - that the provider deactivates itself rather than being turned off - distinguishes this row from the one above it.
| | `✗ No transport configured` | No transport environment variables are set. | Follow the [Airflow setup guide][2] to configure a transport. | | ||
| | `✗ OpenLineage provider is turned off` | The provider is explicitly disabled by `AIRFLOW__OPENLINEAGE__DISABLED`, `OPENLINEAGE_DISABLED`, or `openlineage.disabled` in airflow.cfg. | Remove or set the disable variable to `false`. | | ||
| | `✗ OpenLineage provider is not active (no transport configuration found)` | No transport configuration was found. | Follow the [Airflow setup guide][2] to configure a transport. | | ||
| | `✗ Failed to resolve active transport` | The transport could not be instantiated. | Verify the transport configuration is valid and the provider is active. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `✗ Failed to resolve active transport` | The transport could not be instantiated. | Verify the transport configuration is valid and the provider is active. | | |
| | `✗ Failed to resolve active transport` | The transport could not be instantiated from the resolved configuration. | Verify the transport configuration is valid and well-formed. Check the task log for the underlying error. | |
This message only appears when the provider is active, since resolve_transport() is gated behind that check - so "verify the provider is active" sends the reader down a dead end.
| | `✗ Transport Type: Console (won't send events to Datadog)` | Transport is set to `console`. | Change the transport to `datadog` or `http` pointing to the Datadog intake URL. | | ||
| | `! Transport does not appear to point to a Datadog endpoint` | The transport URL does not match a known Datadog domain. | Verify the URL points to a Datadog intake endpoint. | | ||
| | `✗ Network connectivity check failed` | Airflow workers cannot reach the Datadog intake endpoint. | Check firewall or network policies; confirm the URL and port 443 are accessible. | | ||
| | `✗ OpenLineage listener is not accessible` | The provider plugin cannot be imported, no listeners are registered, or multiple listeners are found. The specific cause is logged earlier in the task log. | Confirm the package is installed on **both scheduler and worker** pods/processes. If the plugin loaded but no listeners are active, check provider version compatibility. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `✗ OpenLineage listener is not accessible` | The provider plugin cannot be imported, no listeners are registered, or multiple listeners are found. The specific cause is logged earlier in the task log. | Confirm the package is installed on **both scheduler and worker** pods/processes. If the plugin loaded but no listeners are active, check provider version compatibility. | | |
| | `✗ OpenLineage listener is not accessible` | The provider plugin cannot be imported, no listeners are registered, or multiple listeners are found. The specific cause is logged earlier in the task log. | Confirm the package is installed on **both scheduler and worker** pods or processes. If the plugin loaded but no listeners are active, check provider version compatibility. | |
- Add '-' (check skipped) as fourth symbol in the legend - Update 'Enabled state' row in overview table to 'Provider active' - Fix broken Airflow docs URL (guides/user.html -> configurations-ref.html) - Add 'All remaining checks are skipped' to package-not-installed row - Backtick airflow.cfg and fix resolution wording for provider-turned-off row - Explain mechanism in cause for provider-not-active row - Remove 'provider is active' from failed-to-resolve-transport resolution - Use 'pods or processes' in listener row
maxvp
reviewed
Aug 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces the embedded OpenLineage validation DAG in the Airflow troubleshooting docs with the latest version, and updates the Understand the output section to match the new output format.
Changes
Embedded DAG code
is_disabled(boolean) withprovider_active+inactive_reason("explicit"|"no_config"|None) to distinguish explicitly disabled from no-transport-config_check_connection_transportfor Airflow connection (conn_id) validationap2.datadoghq.com,uk1.datadoghq.com)conn_idin conflict detectionvalidate_connection→validate_transport_config+resolve_transportis_ol_disabled→check_provider_enabledcheck_is_datadog(logic moved intoresolve_transport)Understand the output section
✗ OpenLineage is disabled→ split into✗ OpenLineage provider is turned offand✗ OpenLineage provider is not active (no transport configuration found)✗ No transport configured→✗ Failed to resolve active transport! Transport does not appear to point to a Datadog endpoint✗ OpenLineage not installed properlyto note all subsequent checks were skipped✗ OpenLineage listener is not accessibleto cover import failure, zero listeners, and multiple listenersValidation
The output format changes were validated by simulating DAG runs under multiple failure scenarios (healthy, provider disabled, package not installed, console transport, non-Datadog URL, failed transport resolution, network failure, listener failures) and confirming the documented output matches the actual log output.