What causes "panel.addToMusicSheet.toast.fail" in maotoumao/MusicFree?

Use a unique, non-empty sheet name — duplicates typically reject creation.

panel.addToMusicSheet.toast.fail

Error message

panel.addToMusicSheet.toast.fail

What it means

When the user confirms creating a new music sheet from the AddToMusicSheet panel, `onSheetCreated` calls the music sheet API to create the sheet and add the track inside a try/catch. On any rejection the panel shows the localized failure toast `panel.addToMusicSheet.toast.fail`. It means sheet creation or the add-to-sheet operation failed (storage, duplicate, or plugin/data error), not a crash.

Source

Thrown at src/components/panels/types/addToMusicSheet.tsx:65

                            }}
                            ListHeaderComponent={
                                <ListItem
                                    withHorizontalPadding
                                    key="new"
                                    onPress={() => {
                                        showPanel("CreateMusicSheet", {
                                            defaultName: newSheetDefaultName,
                                            async onSheetCreated(sheetId) {
                                                try {
                                                    await MusicSheet.addMusic(
                                                        sheetId,
                                                        musicItem,
                                                    );
                                                    Toast.success(
                                                        t("panel.addToMusicSheet.toast.success"),
                                                    );
                                                } catch {
                                                    Toast.warn(
                                                        t("panel.addToMusicSheet.toast.fail"),
                                                    );
                                                }
                                            },
                                            onCancel() {
                                                showPanel("AddToMusicSheet", {
                                                    musicItem: musicItem,
                                                    newSheetDefaultName,
                                                });
                                            },
                                        });
                                    }}>
                                    <ListItem.ListItemImage
                                        fallbackImg={ImgAsset.add}
                                    />
                                    <ListItem.Content title={t("panel.addToMusicSheet.newMusicSheet")} />
                                </ListItem>
                            }

View on GitHub (pinned to d118b18b3d)

Solutions

Use a unique, non-empty sheet name — duplicates typically reject creation.
Retry the operation; if it persists, restart the app to reinitialize the music-sheet store.
Verify the track itself plays correctly first; a malformed musicItem from a faulty plugin can fail the add step — update or disable that plugin.
Check device storage availability and app data permissions if failures are consistent.
If the sheet was created but the toast still shows fail, open the sheet list to confirm state before retrying to avoid duplicates.

Example fix

// before: adding a track with a missing id from a broken plugin
await addMusicToSheet(createdSheetId, musicItem);

// after: validate first
if (!musicItem?.id || !musicItem?.title || !musicItem?.artist) {
    Toast.warn('歌曲信息不完整，无法添加');
    return;
}
await addMusicToSheet(createdSheetId, musicItem);

Defensive patterns

Strategy: validation

Validate before calling

import { useMusicSheetStore } from '@/store/musicSheet';

async function validateSheetName(name: string) {
    const trimmed = name.trim();
    if (!trimmed) return '歌单名不能为空';
    if (useMusicSheetStore.getState().musicSheets.some(s => s.title === trimmed)) {
        return '歌单名已存在';
    }
    return null;
}

const err = await validateSheetName(sheetName);
if (err) {
    Toast.warn(err);
    return;
}
// proceed with create + addMusicToSheet

Type guard

function isValidMusicItem(item: IMusicItem | null | undefined):
    item is IMusicItem {
    return !!item && typeof item.id !== 'undefined'
        && typeof item.title === 'string' && item.title.length > 0
        && typeof item.artist === 'string';
}

Try / catch

try {
    const sheetId = await MusicSheetApi.createMusicSheet(name);
    await MusicSheetApi.addMusicToSheet(sheetId, musicItem);
    Toast.success(t('panel.addToMusicSheet.toast.success'));
} catch (e) {
    console.warn('addToMusicSheet failed', e);
    Toast.warn(t('panel.addToMusicSheet.toast.fail'));
}

Prevention

Enforce unique, non-empty sheet names in the CreateMusicSheet dialog before submission.
Validate musicItem fields (id, title, artist) before adding tracks sourced from plugins.
Check storage availability if persistence writes fail repeatedly.
Show distinct messages for 'create failed' vs 'add failed' to make diagnosis easier for users.

When it happens

Trigger: CreateMusicSheet dialog's onOk creates a sheet with a name that already exists or is empty/invalid, the underlying storage write (MMKV/async storage) rejects, or the addMusicToSheet call fails for the collected musicItem(s), causing the catch branch to fire.

Common situations: User enters a duplicate sheet name; device storage is full or storage permission issues corrupt the persistence layer; adding a track whose musicItem lacks required fields (id/title/artist) from a broken plugin; concurrent sheet creation races.

Related errors

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