panel.musicItemLyricOptions.desktopLyricPermissionError

Error message

panel.musicItemLyricOptions.desktopLyricPermissionError

What it means

When enabling the status-bar (desktop) lyric overlay, the app first checks LyricUtil.checkSystemAlertPermission(). If permission is missing, it requests it via requestSystemAlertPermission() and unconditionally warns with this toast in .finally() — i.e. shown whenever the overlay permission was not already granted (Android 'Display over other apps'). The lyric overlay is not started in this pass.

Solutions

Manually grant 'Display over other apps' permission to MusicFree in Android Settings > Apps > Special app access.
Re-toggle the desktop lyric option after granting permission.
Developer: await requestSystemAlertPermission() and re-check checkSystemAlertPermission() before warning, so the toast only appears when the grant actually failed.
Update LyricUtil/native module if permission callbacks are broken on newer Android versions.

Example fix

// before
LyricUtil.requestSystemAlertPermission().finally(() => {
    Toast.warn(t("panel.musicItemLyricOptions.desktopLyricPermissionError"));
});
// after
await LyricUtil.requestSystemAlertPermission();
if (!(await LyricUtil.checkSystemAlertPermission())) {
    Toast.warn(t("panel.musicItemLyricOptions.desktopLyricPermissionError"));
} else {
    LyricUtil.showStatusBarLyric("MusicFree", statusBarLyricConfig ?? {});
    Config.setConfig("lyric.showStatusBarLyric", true);
}

Defensive patterns

Strategy: fallback

Validate before calling

const hasPermission = await LyricUtil.checkSystemAlertPermission();
if (!hasPermission) {
    // prompt user to grant overlay permission manually before enabling the lyric
    LyricUtil.requestSystemAlertPermission();
    return;
}

Try / catch

try {
    await LyricUtil.requestSystemAlertPermission();
    if (await LyricUtil.checkSystemAlertPermission()) {
        LyricUtil.showStatusBarLyric("MusicFree", config);
    } else {
        Toast.warn(t("panel.musicItemLyricOptions.desktopLyricPermissionError"));
    }
} catch {
    Toast.warn(t("panel.musicItemLyricOptions.desktopLyricPermissionError"));
}

Prevention

On first launch, prompt for 'Display over other apps' permission before offering desktop lyrics.
Re-check permission after every request instead of assuming grant/deny.
Provide a deep-link to the app's overlay-permission settings page.
On iOS or unsupported platforms, hide the desktop-lyric option entirely.

When it happens

Trigger: Pressing the enable-desktop-lyric option in MusicItemLyricOptions (musicItemLyricOptions.tsx:99-124) while lyric.showStatusBarLyric is false and LyricUtil.checkSystemAlertPermission() resolves false; the toast fires in the .finally() of requestSystemAlertPermission regardless of whether the user granted it.

Common situations: Fresh Android install where SYSTEM_ALERT_WINDOW is denied by default; user denies the 'draw over other apps' dialog; Android 10+ restrictions on granting overlay permission; running on iOS where the permission model differs and the check fails.

Related errors

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

Appendix: source

Thrown at src/components/panels/types/musicItemLyricOptions.tsx:122

                    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("panel.musicItemLyricOptions.desktopLyricPermissionError"));
                        });
                    }
                } else {
                    LyricUtil.hideStatusBarLyric();
                    Config.setConfig("lyric.showStatusBarLyric", false);
                }
                hidePanel();
            },
        },
        {
            icon: "arrow-up-tray",
            title: t("panel.musicItemLyricOptions.uploadLocalLyric"),
            async onPress() {
                try {
                    const result = await getDocumentAsync({
                        copyToCacheDirectory: true,
                    });
                    if (result.canceled) {

View on GitHub (pinned to d118b18b3d)