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.

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)

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.