maotoumao/MusicFree · warning

panel.musicItemLyricOptions.settingFail

Error message

panel.musicItemLyricOptions.settingFail

What it means

This is a user-facing toast shown when uploading a local lyric file for a music item fails. The onPress handler calls lyricManager.uploadLocalLyric(musicItem, lyricContent) after reading a local .lrc file; any exception thrown (file read error, media library write failure, invalid musicItem) is caught and surfaced as this toast with the underlying exception message as 'reason'.

Solutions

  1. Check the console.log(e) output and fix the underlying reason shown in the toast
  2. Verify the musicItem comes from a plugin/media source that supports local lyric association (has valid platform/id)
  3. Ensure the selected lyric file is a valid, non-empty .lrc with utf8 encoding
  4. Update or reinstall the media plugin responsible for the track

Example fix

// before
await lyricManager.uploadLocalLyric(musicItem, lyricContent);
// after
if (!musicItem?.id || !lyricContent?.trim()) {
    throw new Error('invalid music item or empty lyric file');
}
await lyricManager.uploadLocalLyric(musicItem, lyricContent);
Defensive patterns

Strategy: try-catch

Validate before calling

// before upload
if (!musicItem?.id || !lyricContent?.trim()) {
    Toast.warn('请选择有效的歌词文件');
    return;
}

Type guard

function isValidMusicItem(m: any): m is IMusicItem {
    return !!m && typeof m.id !== 'undefined' && typeof m.platform === 'string';
}

Try / catch

try {
    await lyricManager.uploadLocalLyric(musicItem, lyricContent);
    Toast.success(t('toast.settingSuccess'));
} catch (e: any) {
    console.warn(e);
    Toast.warn(t('panel.musicItemLyricOptions.settingFail', { reason: e?.message }));
}

Prevention

When it happens

Trigger: Tapping 'set lyric from local file' when the lyric file read succeeds but lyricManager.uploadLocalLyric throws — e.g. musicItem has no valid id/platform, the media library rejects the write, or lyricContent is empty/invalid.

Common situations: User picks an unsupported or empty .lrc file; the selected track is from a plugin whose musicItem lacks a stable id so association fails; filesystem permission issues on the device; plugin media lib not supporting local lyrics.

Related errors

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

Appendix: source

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

            icon: "arrow-up-tray",
            title: t("panel.musicItemLyricOptions.uploadLocalLyric"),
            async onPress() {
                try {
                    const result = await getDocumentAsync({
                        copyToCacheDirectory: true,
                    });
                    if (result.canceled) {
                        return;
                    }
                    const pickedDoc = result.assets[0].uri;
                    const lyricContent = await readAsStringAsync(pickedDoc, {
                        encoding: "utf8",
                    });                    await lyricManager.uploadLocalLyric(musicItem, lyricContent);
                    Toast.success(t("toast.settingSuccess"));
                    hidePanel();
                } catch (e: any) {
                    console.log(e);
                    Toast.warn(t("panel.musicItemLyricOptions.settingFail", {
                        reason: e?.message,
                    }));
                }
            },
        },
        {
            icon: "arrow-up-tray",
            title: t("panel.musicItemLyricOptions.uploadLocalLyricTranslation"),
            async onPress() {
                try {
                    const result = await getDocumentAsync({
                        copyToCacheDirectory: true,
                    });
                    if (result.canceled) {
                        return;
                    }
                    const pickedDoc = result.assets[0].uri;
                    const lyricContent = await readAsStringAsync(pickedDoc, {

View on GitHub (pinned to d118b18b3d)