maotoumao/MusicFree · warning

toast.noFloatWindowPermission

Error message

toast.noFloatWindowPermission

What it means

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.

Source

Thrown at src/pages/setting/settingTypes/basicSetting.tsx:726

                    if (hasPermission) {
                        const statusBarLyricConfig = {
                            topPercent: Config.getConfig("lyric.topPercent"),
                            leftPercent: Config.getConfig("lyric.leftPercent"),
                            align: Config.getConfig("lyric.align"),
                            color: Config.getConfig("lyric.color"),
                            backgroundColor: Config.getConfig("lyric.backgroundColor"),
                            widthPercent: Config.getConfig("lyric.widthPercent"),
                            fontSize: Config.getConfig("lyric.fontSize"),
                        };
                        LyricUtil.showStatusBarLyric(
                            "MusicFree",
                            statusBarLyricConfig ?? {}
                        );
                        Config.setConfig("lyric.showStatusBarLyric", true);
                    } else {
                        LyricUtil.requestSystemAlertPermission().finally(() => {
                            Toast.warn(t("toast.noFloatWindowPermission"));
                        });
                    }
                } else {
                    LyricUtil.hideStatusBarLyric();
                    Config.setConfig("lyric.showStatusBarLyric", false);
                }
            } catch { }
        },
    );

    const alignStatusBarLyric = createRadio(
        t("basicSettings.lyric.align"),
        "lyric.align",
        [
            NativeTextAlignment.LEFT,
            NativeTextAlignment.CENTER,
            NativeTextAlignment.RIGHT,
        ],

View on GitHub (pinned to d118b18b3d)

Solutions

1. 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.
2. On aggressive OEM ROMs (MIUI/EMUI), additionally enable 'Display pop-up windows while running in background' and autostart for the app.
3. 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.
4. If testing on an emulator, grant the permission via `adb shell appops set <package> SYSTEM_ALERT_WINDOW allow`.

Example fix

// before
LyricUtil.requestSystemAlertPermission().finally(() => {
    Toast.warn(t("toast.noFloatWindowPermission"));
});
// after
const granted = await LyricUtil.requestSystemAlertPermission();
if (await LyricUtil.checkSystemAlertPermission()) {
    LyricUtil.showStatusBarLyric("MusicFree", statusBarLyricConfig ?? {});
    Config.setConfig("lyric.showStatusBarLyric", true);
} else {
    Toast.warn(t("toast.noFloatWindowPermission"));
}

const hasPermission = await LyricUtil.checkSystemAlertPermission();
if (!hasPermission) {
    // guide user to settings before attempting to show the overlay
    await LyricUtil.requestSystemAlertPermission();
    if (!(await LyricUtil.checkSystemAlertPermission())) {
        Toast.warn(t("toast.noFloatWindowPermission"));
        return;
    }
}

try {
    await enableStatusBarLyric();
} catch (e) {
    // permission check calls may reject on some devices
    Toast.warn(t("toast.noFloatWindowPermission"));
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• panel.musicItemLyricOptions.desktopLyricPermissionError
• 状态栏歌词开启失败，请到手机系统设置打开悬浮窗权限
• toast.folderNotExistOrNoPermission

AI-assisted analysis of maotoumao/MusicFree@d118b18b3d (2026-08-30). Data as JSON: /api/errors/91449afc8a1041df. Report an issue: GitHub.