SystemBars: safe area CSS injection throws "Cannot read properties of null" on startup (Android 16)

オープン 初心者向け
#8,530 コメント 2 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 2 日以内に返信

@kttalley がすでに取り組んでいます。

2026年9月30日 から。

  • #8636 @kttalley による — オープン

評価

難易度
2/5
見積もり時間
1〜3時間
初心者へのやさしさ
78/100
issue の種類
バグ
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
android, css, java, javascript
領域
mobile-dev

調査の方向性

Capacitor 8.4.1 の 250 行目付近にある SystemBars.injectSafeAreaCSS() から調査を開始し、その setOnApplyWindowInsetsListener の呼び出し元と注入されるスクリプトを確認します。SDK 36 を対象とする Android アプリを、物理的な Android 16 デバイス上で使って再現します。起動時に safe-area CSS エラーが出力されず、レイアウトと CSS 変数が変更されないことを確認できれば完了です。

索引モデルが issue の本文から書いたものです。

説明

triage
Capacitor Version

Hit this while upgrading to Capacitor 8 and targeting SDK 36. Every app launch logs:

E Capacitor/Console: File:  - Line 6 - Msg: Error injecting safe area CSS: TypeError: Cannot read properties of null (reading 'style')

Environment: @capacitor/android 8.4.1, compileSdk/targetSdk 36, AGP 8.13.0, Gradle 8.14.3, JDK 21, Samsung device on Android 16.

What's happening

It's coming from SystemBars.injectSafeAreaCSS() (~line 250 in 8.4.1). The injected script does:

"""
try {
  document.documentElement.style.setProperty("--safe-area-inset-top", "%dpx");
  document.documentElement.style.setProperty("--safe-area-inset-right", "%dpx");
  document.documentElement.style.setProperty("--safe-area-inset-bottom", "%dpx");
  document.documentElement.style.setProperty("--safe-area-inset-left", "%dpx");
} catch(e) { console.error('Error injecting safe area CSS:', e); }
"""

document.documentElement is null when this runs. The "Line 6" in the logcat output is the catch line inside that text block, which lines up.

As far as I can tell, injectSafeAreaCSS gets called from the setOnApplyWindowInsetsListener callback, and that fires before the WebView document exists on first layout. The bridge.getWebView() != null guard passes — the WebView object is there — but there's no document in it yet. Later passes work fine, which is why the CSS variables do end up set correctly and nothing visibly breaks.

Why I couldn't just work around it

Tried insetsHandling: "disable" first, which was a mistake — on Android 16 SystemBars is the only thing actually insetting content below the status bar. StatusBar.setOverlaysWebView() uses setSystemUiVisibility, which is a no-op at API 35+. So disabling the plugin to kill the error breaks the layout the plugin is there to provide. Ended up patching the framework instead, which isn't great to have to carry.

Fix

Null guard in the injected script:

try {
  if (document.documentElement) {
    document.documentElement.style.setProperty("--safe-area-inset-top", "%dpx");
    // ...etc
  }
} catch(e) { console.error('Error injecting safe area CSS:', e); }

No-op when the DOM's already there, so no behaviour change. Ran this on a physical Android 16 device — error's gone, layout is identical, no other console errors.

Repro

Cap 8.4.1 Android app, targetSdk 36, viewport-fit=cover in the viewport meta, launch on an Android 16 device, watch the console.

Happy to put up a PR if it's wanted.

Other API Details

Platforms Affected
  • iOS
  • Android
  • Web
Current Behavior

On every app launch, an error is logged to the console:

Error injecting safe area CSS: TypeError: Cannot read properties of null (reading 'style')

Full logcat line:
E Capacitor/Console: File: - Line 6 - Msg: Error injecting safe area CSS: TypeError: Cannot read properties of null (reading 'style')

It comes from SystemBars.injectSafeAreaCSS(). The injected script calls
document.documentElement.style.setProperty(...), but document.documentElement is
null at that moment — the "Line 6" in the log is the catch line inside that Java
text block, which lines up with the setProperty calls throwing.

As far as I can tell, injectSafeAreaCSS gets called from the
setOnApplyWindowInsetsListener callback, and that fires before the WebView
document exists on first layout. The bridge.getWebView() != null guard passes
— the WebView object is there — but there's no document in it yet.

Later passes succeed, so the --safe-area-inset-* variables do end up set
correctly and nothing visibly breaks. It's just an error on every startup.

Worth noting: insetsHandling: "disable" isn't a viable workaround. On Android 16
SystemBars is the only thing actually insetting content below the status bar —
StatusBar.setOverlaysWebView() uses setSystemUiVisibility, which is a no-op at
API 35+. So disabling the plugin to silence the error breaks the layout the
plugin is there to provide.

Expected Behavior

The injected script should no-op when the document isn't available yet, rather
than throwing and logging an error on every launch.

A null guard is enough:

try {
if (document.documentElement) {
document.documentElement.style.setProperty("--safe-area-inset-top", "%dpx");
...
}
} catch(e) { console.error('Error injecting safe area CSS:', e); }

It's a no-op whenever the DOM already exists, so no behaviour change. I applied
exactly this locally and verified on a physical Android 16 device — the error is
gone, no other console errors, and the layout is unchanged.

Happy to open a PR if that's useful.

Project Reproduction

No standalone repro repo — but this should reproduce on any Capacitor 8.4.1 Android app targeting SDK 36 with viewport-fit=cover in the viewport meta tag. Launch on an Android 16 device and watch the console on startup. The throw is inside Capacitor's own injected script, so I don't think app code is involved.

Additional Information

No response

主要言語
TypeScript
スター
17.1k
フォーク
1.3k
平均マージ
2日 1時間
マージ済み PR(30日)
32

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

ionic-team/capacitor のほかの issue

ionic-team/capacitor の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。