{"record":{"id":"91449afc8a1041df","repo":"maotoumao/MusicFree","slug":"toast-nofloatwindowpermission","errorCode":null,"errorMessage":"toast.noFloatWindowPermission","messagePattern":"toast\\.noFloatWindowPermission","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/pages/setting/settingTypes/basicSetting.tsx","lineNumber":726,"sourceCode":"\r\n                    if (hasPermission) {\r\n                        const statusBarLyricConfig = {\r\n                            topPercent: Config.getConfig(\"lyric.topPercent\"),\r\n                            leftPercent: Config.getConfig(\"lyric.leftPercent\"),\r\n                            align: Config.getConfig(\"lyric.align\"),\r\n                            color: Config.getConfig(\"lyric.color\"),\r\n                            backgroundColor: Config.getConfig(\"lyric.backgroundColor\"),\r\n                            widthPercent: Config.getConfig(\"lyric.widthPercent\"),\r\n                            fontSize: Config.getConfig(\"lyric.fontSize\"),\r\n                        };\r\n                        LyricUtil.showStatusBarLyric(\r\n                            \"MusicFree\",\r\n                            statusBarLyricConfig ?? {}\r\n                        );\r\n                        Config.setConfig(\"lyric.showStatusBarLyric\", true);\r\n                    } else {\r\n                        LyricUtil.requestSystemAlertPermission().finally(() => {\r\n                            Toast.warn(t(\"toast.noFloatWindowPermission\"));\r\n                        });\r\n                    }\r\n                } else {\r\n                    LyricUtil.hideStatusBarLyric();\r\n                    Config.setConfig(\"lyric.showStatusBarLyric\", false);\r\n                }\r\n            } catch { }\r\n        },\r\n    );\r\n\r\n    const alignStatusBarLyric = createRadio(\r\n        t(\"basicSettings.lyric.align\"),\r\n        \"lyric.align\",\r\n        [\r\n            NativeTextAlignment.LEFT,\r\n            NativeTextAlignment.CENTER,\r\n            NativeTextAlignment.RIGHT,\r\n        ],\r","sourceCodeStart":708,"sourceCodeEnd":744,"githubUrl":"https://github.com/maotoumao/MusicFree/blob/d118b18b3d0c904400f7eea7bf99c0ceec6c1aee/src/pages/setting/settingTypes/basicSetting.tsx#L708-L744","documentation":"This warning toast is shown when the user tries to enable the status-bar (floating) lyric overlay but the app lacks the Android SYSTEM_ALERT_WINDOW (draw-over-other-apps) permission. The code checks LyricUtil.checkSystemAlertPermission(); when it returns false it calls LyricUtil.requestSystemAlertPermission() and, once that promise settles, warns the user because the overlay cannot be shown without the grant. It is a UX notice, not an exception: the feature is simply not enabled until the user grants the permission in system settings.","triggerScenarios":"Toggling the 'showStatusBarLyric' switch in LyricSetting to ON while `await LyricUtil.checkSystemAlertPermission()` resolves false; the warning fires in the `.finally()` of `LyricUtil.requestSystemAlertPermission()` regardless of whether the user granted or dismissed the permission dialog.","commonSituations":"Android 6.0+ where the overlay permission is off by default; Xiaomi/MIUI, EMUI, ColorOS and other OEM ROMs that auto-deny or hide the 'Display over other apps' setting; fresh installs where the user never granted the special permission; Android emulators without the overlay permission pre-granted.","solutions":["Direct the user to system settings: open 'Settings > Apps > MusicFree > Display over other apps' (or call LyricUtil/request overlay permission intent) and enable it, then toggle the lyric switch again.","On aggressive OEM ROMs (MIUI/EMUI), additionally enable 'Display pop-up windows while running in background' and autostart for the app.","Re-check the permission after the request returns (checkSystemAlertPermission) and only enable lyric.showStatusBarLyric=true when it is actually granted; guide the user back if still denied.","If testing on an emulator, grant the permission via `adb shell appops set <package> SYSTEM_ALERT_WINDOW allow`."],"exampleFix":"// before\nLyricUtil.requestSystemAlertPermission().finally(() => {\n    Toast.warn(t(\"toast.noFloatWindowPermission\"));\n});\n// after\nconst granted = await LyricUtil.requestSystemAlertPermission();\nif (await LyricUtil.checkSystemAlertPermission()) {\n    LyricUtil.showStatusBarLyric(\"MusicFree\", statusBarLyricConfig ?? {});\n    Config.setConfig(\"lyric.showStatusBarLyric\", true);\n} else {\n    Toast.warn(t(\"toast.noFloatWindowPermission\"));\n}","handlingStrategy":"validation","validationCode":"const hasPermission = await LyricUtil.checkSystemAlertPermission();\nif (!hasPermission) {\n    // guide user to settings before attempting to show the overlay\n    await LyricUtil.requestSystemAlertPermission();\n    if (!(await LyricUtil.checkSystemAlertPermission())) {\n        Toast.warn(t(\"toast.noFloatWindowPermission\"));\n        return;\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    await enableStatusBarLyric();\n} catch (e) {\n    // permission check calls may reject on some devices\n    Toast.warn(t(\"toast.noFloatWindowPermission\"));\n}","preventionTips":["Always call checkSystemAlertPermission() before enabling overlay features on Android.","Treat requestSystemAlertPermission()'s completion as insufficient — re-verify with a fresh check.","Test on OEM ROMs (MIUI/EMUI/ColorOS) where overlay permissions behave differently.","Persist lyric.showStatusBarLyric only after permission is confirmed granted."],"tags":["android","permissions","overlay","system-alert-window"],"backgroundTag":"missing-overlay-permission","analyzedSha":"d118b18b3d0c904400f7eea7bf99c0ceec6c1aee","analyzedAt":"2026-08-30T11:49:12.932Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}