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'.

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)

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.