Break out of iframe from Airflow 2 dbt Docs 404 link by pankajastro · Pull Request #2685 · astronomer/astronomer-cosmos

pankajastro · 2026-05-15T14:33:42Z

Summary

Fix #1828: when AIRFLOW__COSMOS__DBT_DOCS_DIR points at a missing index.html, the dbt_docs_index endpoint called abort(404) and Flask served Airflow's default 404 template inside the dbt_docs.html iframe. Its "Return to the main page" anchor has no target, so clicking it navigated the iframe to /home — leaving the DAGs view nested inside the dbt Docs frame instead of replacing it.
Serve a small Cosmos-owned dbt_docs_iframe_404.html whose home link uses target="_top" so the click escapes the iframe. catalog.json / manifest.json endpoints still use abort(404) because they are fetched by the docs JS, not rendered visually.
Add a regression test asserting the 404 response body contains target="_top" and the "Return to the main page" copy.

Test plan

CI integration job passes tests/plugin/test_plugin_af2.py, including the new test_dbt_docs_index_404_breaks_out_of_iframe.
Manual repro per the issue: set AIRFLOW__COSMOS__DBT_DOCS_DIR to a non-existent path, open Browse → dbt Docs, click "Return to the main page" → top window navigates to /home (no nested DAGs view inside the iframe).

Demo

Screen.Recording.2026-05-15.at.9.06.17.PM.mov

🤖 Generated with Claude Code

When dbt_docs_dir is set but the configured index.html cannot be loaded, dbt_docs_index() called abort(404) and Flask served Airflow's default 404 template inside the dbt_docs.html iframe. The "Return to the main page" link on that template is a plain anchor, so clicking it navigated the iframe to /home, leaving the DAGs view rendered inside the dbt Docs frame. Serve a small Cosmos-owned 404 template whose home link uses target="_top" so the click escapes the iframe. The catalog.json and manifest.json endpoints still use abort(404) because they are fetched by the docs JS, not rendered visually. Closes #1828 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Fixes a UI bug where the dbt Docs 404 page (Airflow's default) was rendered inside the Cosmos dbt_docs.html iframe and the "Return to the main page" link did not break out of the iframe. The PR introduces a Cosmos-owned 404 template whose home link uses target="_top", and updates the Airflow 2 plugin's dbt_docs_index endpoint to render it instead of calling abort(404).

Changes:

New cosmos/plugin/templates/dbt_docs_iframe_404.html template with a target="_top" home link.
dbt_docs_index in cosmos/plugin/airflow2.py now returns the new template with status 404 instead of abort(404) (catalog/manifest endpoints still use abort(404) since they aren't visually rendered).
Regression test in tests/plugin/test_plugin_af2.py asserting the 404 body contains target="_top" and the expected copy.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
cosmos/plugin/templates/dbt_docs_iframe_404.html	New iframe-aware 404 page with `target="_top"` link to Airflow home.
cosmos/plugin/airflow2.py	Replace `abort(404)` in `dbt_docs_index` with rendering the new template; loosen return type annotation to `Any`.
tests/plugin/test_plugin_af2.py	Add regression test verifying the 404 body breaks out of the iframe.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Use the same verdana, center-aligned layout and pin_100.png logo as Airflow's www/templates/airflow/error.html so the iframed page looks like a native Airflow 404 instead of a left-aligned plain-text block. The home link still uses target="_top" so it breaks out of the iframe. The Cosmos plugin has no static folder of its own, so url_for('static') falls through to Airflow's app-level static endpoint and resolves the pin asset correctly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

pankajkoti

Nice fix, can we alter the PR title to reflect the fix targets Airflow 2 dbt docs ".........Airflow 2 dbt Docs......."?

## Summary - Fix [#1828](#1828): when `AIRFLOW__COSMOS__DBT_DOCS_DIR` points at a missing `index.html`, the `dbt_docs_index` endpoint called `abort(404)` and Flask served Airflow's default 404 template inside the `dbt_docs.html` iframe. Its "Return to the main page" anchor has no `target`, so clicking it navigated the iframe to `/home` — leaving the DAGs view nested inside the dbt Docs frame instead of replacing it. - Serve a small Cosmos-owned `dbt_docs_iframe_404.html` whose home link uses `target="_top"` so the click escapes the iframe. `catalog.json` / `manifest.json` endpoints still use `abort(404)` because they are fetched by the docs JS, not rendered visually. - Add a regression test asserting the 404 response body contains `target="_top"` and the "Return to the main page" copy. ## Test plan - [ ] CI integration job passes `tests/plugin/test_plugin_af2.py`, including the new `test_dbt_docs_index_404_breaks_out_of_iframe`. - [ ] Manual repro per the issue: set `AIRFLOW__COSMOS__DBT_DOCS_DIR` to a non-existent path, open **Browse → dbt Docs**, click "Return to the main page" → top window navigates to `/home` (no nested DAGs view inside the iframe). Demo https://github.com/user-attachments/assets/c242f4bc-9f0e-498d-842c-9c3f53ac5140 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Both PRs closed milestone-attached issues but weren't themselves assigned to the milestone. Now assigned, cherry-picked, and documented: - #2685 (Bug Fix): break out of iframe from Airflow 2 dbt Docs 404 link — closes issue #1828. - #2642 (Docs): document the incremental-model limitation for ExecutionMode.AIRFLOW_ASYNC — closes issue #2351.

tatiana · 2026-05-21T16:35:37Z

🚀 Released in Cosmos 1.14.2 (PyPI).

@MichaelRBlack

## CHANGELOG entry 1.14.2 (2026-05-21) ------------------- Behaviour Changes These changes adjust observable behaviour of the ``ExecutionMode.WATCHER`` execution mode. None of them breaks the public Cosmos API, but users relying on undocumented internals (graph wiring assertions, XCom backup Variable names, retry-on-recovery semantics, or retry log format) should review before upgrading. * ``ExecutionMode.WATCHER`` + ``depends_on_past=True``: when the producer task has ``depends_on_past=True`` (typically set via ``default_args``), the producer-done gateway task inside ``DbtTaskGroup`` is now wired downstream of every consumer task, in addition to the producer. This is required so that ``wait_for_downstream`` gating behaves correctly across DAG runs and the task group acts as a single unit that must fully succeed before the next run starts. Users with ``depends_on_past=False`` (the default) see no topology change. See #2615. * ``ExecutionMode.WATCHER`` downstream retry on upstream recovery: dbt models that were skipped after an upstream-failure event are now retried in the same DAG run when the upstream task succeeds on retry. Previously these models remained skipped for the run. See #2684. * ``ExecutionMode.WATCHER`` consumer-retry log format: the consumer's fallback ``dbt`` invocation no longer inherits the producer's internal ``--log-format json`` flag, so retry task logs now default to dbt's normal text format. Users who relied on JSON output in retry logs can opt in via ``operator_args={"dbt_cmd_flags": ["--log-format", "json"]}``. See #2713. * ``ExecutionMode.WATCHER`` XCom-backup Variable key scheme: the per-model XCom backup Variable key now includes the full task-group path and sanitises disallowed characters (``+`` / ``:``) from ``run_id``. External monitoring or cleanup scripts that match the old key pattern will need updating. See #2629 and #2683. Bug Fixes * Sanitize disallowed characters from XCom backup variable key by @MichaelRBlack in #2629 * Prevent watcher producers from colliding on one XCom-backup key by @tatiana in #2683 * Retry watcher downstream models on upstream-failure recovery by @tatiana in #2684 * Fix ``ExecutionMode.WATCHER`` interaction with ``depends_on_past`` by @johnhoran in #2615 * Strip ``--log-format`` from producer flags on watcher consumer retry by @tatiana in #2713 * Fix duplicate ``deferrable`` kwarg in ``DbtRunAirflowAsyncBigqueryOperator`` by @pankajastro in #2616 * Fix dbt docs iframe ``src`` missing deployment path prefix by @pankajastro in #2640 * Defer ``TaskInstance`` import in cluster policy to fix Sentry init crash by @pankajastro in #2662 * Restore type hints broken by lazy imports in ``cosmos/__init__.py`` by @pankajastro in #2647 * Fix ``ExecutionMode.WATCHER`` non-dbt stdout being suppressed from logs by @pankajastro in #2654 * Fix test sensor retry behaviour in ``ExecutionMode.WATCHER`` by @pankajkoti in #2658 * Fix watcher fallback selector for versioned dbt models by @pankajkoti in #2659 * Break out of iframe from Airflow 2 dbt Docs 404 link by @pankajastro in #2685 Docs * Document source freshness aware execution for ``ExecutionMode.WATCHER`` by @pankajastro in #2617 * Add reference docs for ``DbtRunLocalOperator``, ``DbtTestLocalOperator``, ``DbtSnapshotLocalOperator`` and ``DbtBuildLocalOperator`` by @pankajastro in #2643 * Add watcher retry behaviour history documentation by @tatiana in #2600 * Add Apache Airflow® trademark on first prominent mention by @pankajkoti in #2624 * Sentence-case section headings by @pankajkoti in #2630 * Use ``-`` for bullet points by @pankajkoti in #2631 * Drop decorative separator lines by @pankajkoti in #2632 * Normalize heading underlines in ``docs/guides/`` and ``docs/index.rst`` by @pankajkoti in #2664 * Fix broken cross-directory doc links by @pankajastro in #2694 * Fix broken external links in hand-written docs by @pankajastro in #2696 * Document support for Airflow 3.2 in the compatibility policy by @pankajastro in #2652 * Refresh the dbt/Airflow conflicts table to match the compatibility policy by @pankajastro in #2653 * Document incremental model limitation for ``ExecutionMode.AIRFLOW_ASYNC`` by @pankajastro in #2642 Others * Import ``ParamValidationError`` from ``airflow.sdk`` to silence deprecation warning by @pankajastro in #2645 * Import ``DAG`` from ``airflow.sdk`` to silence deprecation warning by @pankajastro in #2644 * Enforce docs style guide via pre-commit hook by @pankajkoti and @tatiana in #2633 * Add Airflow 3.2 to the test matrix in ``CLAUDE.md`` by @pankajastro in #2646 * Document the lazy-logging standard in ``CLAUDE.md`` by @pankajastro in #2679 * Extract watcher XCom-key helpers and inline single-use bindings by @pankajastro in #2673 * Remove leftover ``scripts/airflow3`` directory by @pankajastro in #2661 * Fix ``altered_jaffle_shop`` seed-dep CTE references by @pankajastro in #2690 * Skip Airflow 3.0 integration test stuck on ``example_watcher_with_freshness`` by @pankajastro in #2692 * Fix typo "constrantis" → "constraints" in tests env comment by @pankajastro in #2669 ## Summary Drafts the **Cosmos 1.14.2** release. Latest alpha cut is **1.14.2a4** — refreshed from `1.14.2a3` after maintainers (@pankajastro, @pankajkoti) added 11 more PRs to the milestone: - @pankajastro: #2646, #2652, #2653, #2661, #2669, #2673, #2679, #2690, #2692 - @pankajkoti: #2658, #2659 All 11 picks applied cleanly on top of the existing branch — no additional manual conflict resolution needed. **Excluded:** #2618 ("Improve glossary") — modifies `docs/reference/glossary.rst`, which doesn't exist on `release-1.14` (added on main by #2461, never backported). Deferred to 1.15.0. 33 PRs cherry-picked total (22 in the initial a3 cut + 11 in this a4 refresh); two PRs (#2575, #2618) deliberately held back as 1.15.0 content. ## Milestone [Cosmos 1.14.2](https://github.com/astronomer/astronomer-cosmos/milestone/48) — 33 merged PRs across Bug Fixes, Docs, and Others. ## Inclusion provenance | Path | PRs | Notes | |---|---|---| | **Originally in milestone — a3 cut (12)** | #2629, #2616, #2640, #2662, #2654, #2683, #2684, #2615, #2694, #2696, #2645, #2644 | Assigned by maintainers before the initial release-draft run | | **Pulled in via closed-issue link — a3 cut (1)** | #2647 | Closes milestone issue #2634 ("Typehinting broken with lazy imports") but the PR itself was never assigned to the milestone — included via `closedByPullRequestsReferences` | | **Added during cherry-pick conflict resolution — a3 cut (9)** | #2631, #2624, #2630, #2632, #2664, #2633, #2617, #2600, #2643 | Docs PRs whose absence caused `release-1.14` ↔ `main` textual drift. #2631 caused #2696's conflict; the rest were transitive dependencies (especially #2664, on top of the bullet/heading/trademark sweeps). #2643 was added to unblock #2664's operator-docs conflict | | **Added to milestone after a3 — included in a4 (11)** | #2646, #2652, #2653, #2658, #2659, #2661, #2669, #2673, #2679, #2690, #2692 | Added by @pankajastro and @pankajkoti after the initial draft. All applied cleanly on top of the a3 cherry-picks | | **Deliberately excluded (2)** | #2575, #2618 | #2575: documents `DbtDocsS3KubernetesOperator` with `.. versionadded:: 1.15.0` (already in the `Cosmos 1.15.0` milestone). #2618: improves a glossary file that doesn't exist on `release-1.14` (the stub was added by #2461, not backported) | ### Manual conflict resolution Cherry-picks that needed manual fix-up. Reviewers should double-check the files listed below: | PR | File(s) | Resolution | |---|---|---| | **#2664** | `docs/guides/dbt_docs/generating-docs.rst` | **Substantive exclusion** — manually removed the entire `Upload to S3 from Kubernetes` section (lines ~46–77 of the incoming diff) that documents `DbtDocsS3KubernetesOperator` (1.15.0 feature, PR #2575). Kept HEAD (no S3-from-Kubernetes section). | | **#2664** | `docs/guides/run_dbt/airflow-worker/watcher-execution-mode.rst` | Took incoming side for "Example 1" / "Example 2" heading underlines (`++++` style — matches #2664's normalization across the rest of the file). Also took incoming for em-dash → colon ("Example 1 —" → "Example 1:"). | | **#2664** | `docs/guides/run_dbt/operators/operators.rst` | Auto-resolved once #2643 was cherry-picked first (added missing Run/Test/Snapshot/Build operator reference docs that #2664 expected to be present). | | **#2633** | `docs/guides/run_dbt/airflow-worker/watcher-execution-mode.rst` | Initially took `'''` (Example 1/2 underlines) per #2633's incoming side — this broke the file's heading hierarchy and prevented sphinx from registering the `_watcher-source-freshness:` label, causing the docs build to fail. **Fixed in a follow-up commit** by reverting to `+++` to match main and the rest of the file's level-3 sections. | | **#2617** | `docs/guides/run_dbt/airflow-worker/watcher-execution-mode.rst` | **Substantive trim** — #2617 documented both the 1.14.0 source-freshness execution path AND the 1.15.0 `freshness_callback` override (which ships with #2586, not in this release line). Removed the `literalinclude` of `dev/dags/watcher_with_freshness_check.py` (1.15.0 example DAG, missing on release-1.14) and the surrounding override section so the 1.14.2 docs cover only what the 1.14.x line supports. Surfaced as a `-W` (warnings-as-errors) docs build failure on the first CI run. | | **#2684** | `cosmos/operators/_watcher/state.py` | Took incoming side — added two new frozensets (`DBT_UPSTREAM_FAILURE_SKIP_EVENT_NAMES`, `DBT_SOURCE_FRESHNESS_STALE_STATUSES`) at lines 28–37. HEAD had nothing; incoming had the additions. | | **#2615** | `tests/airflow/test_graph.py` | Took incoming side — added two new tests at the end of the file: `test_add_watcher_producer_task_passes_freshness_callback_via_setup_operator_args` and `test_watcher_dependency_wiring`. HEAD had nothing; incoming had the additions. | All a4 cherry-picks (11) applied without manual intervention. ## Test plan > Long-term goal: automate. For now, please pick the slice relevant to your environment and report deviations as a comment on this PR. ### Watcher mode (Postgres) - [x] @pankajkoti `example_watcher` (`dev/dags/example_watcher.py`) — default watcher run; exercises **#2629** (XCom backup key sanitization triggers on the `+` in any default Airflow run_id) - [x] (@tatiana) **[NEW]** `example_watcher_xcom_collision` (`dev/failed_dags/example_watcher_xcom_collision.py`) — validates **#2683** - [x] @tatiana **[NEW]** `example_watcher_recovers_skipped_downstream` (`dev/failed_dags/example_watcher_recovers_skipped_downstream.py`) — validates **#2684** - [x] @tatiana `example_watcher` with `default_args={"depends_on_past": True}` and ≥2 consecutive runs — validates **#2615** (manual edit; no dedicated example DAG) - [x] @pankajkoti watcher DAG with at least one model that has tests + Airflow retries enabled on the test sensor — validates **#2658** (test sensor retry path) - [x] @pankajkoti watcher DAG referencing a versioned dbt model (e.g. `models/foo_v2.sql`) and triggering the fallback selector path — validates **#2659** ### BigQuery (async) - [x] @tatiana `simple_dag_async` (`dev/dags/simple_dag_async.py`) — validates **#2616** (duplicate `deferrable` kwarg fix) ### dbt docs plugin - [x] (@pankajkoti) `docs_dag` (`dev/dags/dbt_docs.py`) + open the Cosmos dbt docs URL in the Airflow UI under a non-root deployment path — validates **#2640** (iframe `src` deployment prefix) ### Cross-cutting scenarios (no dedicated DAG) - [x] @pankajastro **#2662** — boot Airflow with Cosmos cluster policy + Sentry init; verify no `TaskInstance`-import crash on startup - [x] @pankajastro **#2654** — run a watcher DAG that prints non-dbt stdout (e.g., Snowflake `externalbrowser` auth URL); confirm output reaches task logs - [x] (@pankajkoti) **#2647** — `mypy` / IDE inspection of `from cosmos import DbtDag, ProjectConfig, ProfileConfig, RenderConfig, ExecutionConfig` resolves attributes - [x] @pankajastro **#2645, #2644** — boot Airflow 3 with `airflow.sdk` available; no `ParamValidationError` / `DAG` deprecation warnings from Cosmos imports - [x] @pankajastro **#2673** — verify watcher XCom-key extraction left no behavioural drift (run the existing watcher integration suite end-to-end on Postgres + Airflow 2.10) ### Docs build (covers all docs PRs) - [x] (@pankajkoti) `sphinx-build -W -b html docs docs/_build` succeeds with no warnings (#2617, #2624, #2630, #2631, #2632, #2643, #2600, #2664, #2694, #2696, #2652, #2653) ### Tooling - [x] (@pankajkoti) `pre-commit run check-docs-style --all-files` passes (#2633) ## Reviewer checklist - [x] CHANGELOG section assignments reviewed - [x] Entry wording reviewed - [x] `cosmos/__init__.py` bumped to `1.14.2a4` - [x] Cosmetic docs PRs (#2624, #2630, #2631, #2632, #2633, #2664) confirmed acceptable in patch line - [x] **Manual conflict resolutions** (table above) reviewed file-by-file - [x] Test plan executed on at least Postgres + one warehouse - [x] Ready to mark non-draft --------- Co-authored-by: Michael Black <4128408+MichaelRBlack@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Pankaj Singh <98807258+pankajastro@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Pankaj Koti <pankajkoti699@gmail.com> Co-authored-by: John Horan <jhoran@zendesk.com> Co-authored-by: Copilot <copilot@github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Copilot AI review requested due to automatic review settings May 15, 2026 14:33

pankajastro requested review from a team, corsettigyg, dwreeves and jbandoro as code owners May 15, 2026 14:33

pankajastro requested review from pankajkoti and tatiana May 15, 2026 14:33

pankajastro temporarily deployed to internal May 15, 2026 14:33 — with GitHub Actions Inactive

Copilot started reviewing on behalf of pankajastro May 15, 2026 14:34 View session

Copilot AI reviewed May 15, 2026

View reviewed changes

pankajastro marked this pull request as draft May 15, 2026 14:38

pankajastro temporarily deployed to internal May 15, 2026 15:33 — with GitHub Actions Inactive

pankajastro marked this pull request as ready for review May 15, 2026 15:37

Copilot AI review requested due to automatic review settings May 15, 2026 15:37

Copilot started reviewing on behalf of pankajastro May 15, 2026 15:38 View session

Copilot AI reviewed May 15, 2026

View reviewed changes

pankajkoti approved these changes May 15, 2026

View reviewed changes

pankajastro changed the title ~~Break out of iframe from dbt Docs 404 link~~ Break out of iframe from Airflow 2 dbt Docs 404 link May 18, 2026

pankajastro merged commit 4101685 into main May 18, 2026
124 of 127 checks passed

pankajastro deleted the fix/1828-dbt-docs-iframe-404 branch May 18, 2026 05:28

tatiana added this to the Cosmos 1.14.2 milestone May 21, 2026

tatiana mentioned this pull request May 21, 2026

Release 1.14.2 #2708

Merged

22 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Break out of iframe from Airflow 2 dbt Docs 404 link#2685

Break out of iframe from Airflow 2 dbt Docs 404 link#2685
pankajastro merged 2 commits into
mainfrom
fix/1828-dbt-docs-iframe-404

pankajastro commented May 15, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

pankajkoti left a comment

Uh oh!

Uh oh!

tatiana commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

pankajastro commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

pankajkoti left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tatiana commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pankajastro commented May 15, 2026 •

edited

Loading