Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Troubleshooting and FAQ

Troubleshooting

ffmpeg is not found

suno version ends with ffmpeg: not found on PATH. Install ffmpeg and make sure it is on your PATH. See Installation and ffmpeg. rs-suno needs ffmpeg to produce FLAC (the default format) or ALAC, and animated WebP covers.

FLAC, ALAC, or animated covers fail to encode

Your ffmpeg build is missing an encoder. Check it with:

ffmpeg -hide_banner -encoders | grep -E 'flac|alac|libwebp'

If flac or alac is missing, download in MP3 or WAV, or install a fuller ffmpeg build. If libwebp/libwebp_anim is missing, drop --animated-covers or install an ffmpeg with animated-WebP support.

Authentication failed (exit 4)

The stored token has expired or was rejected. Diagnose it first:

suno doctor --account <account>

Then confirm and re-mint it:

suno auth refresh <account>

If that still fails, the session was rotated (you logged out, or Suno reset it). Get a fresh __client token and set the account’s token in your config file to the new value (run suno version to print the config path). If the account uses token_command, the refreshed secret is picked up automatically on the next run. See Authentication.

“multiple accounts configured; pass –account”

You have more than one account and ran a single-account command without saying which. Add --account <label>, or use --all for sync/copy to run every account.

“account has no configured root and no DEST was given”

The account has no root in its config and you did not pass a destination. Give a DEST on the command line, or set root for the account. --all always needs each account to have a root.

“another suno run is active”

A run holds an exclusive lock (.suno.lock) on the destination while it works. If a previous run crashed, the lock file can be left behind. Once you are sure no run is active, delete the .suno.lock file in the destination directory and try again.

A sync aborted with a safety warning (exit 7)

A deletion safety rule stopped the run because the deletion looked wrong: the listing was empty, or it would have removed a large fraction of your library. Nothing was deleted. This is usually a transient listing problem, so try again later. If you genuinely intend a mass deletion, confirm it explicitly with --min-newest 0 --yes. See deletion safety.

Nothing is being deleted

That is expected when you use --since or --limit. A narrowed or filtered listing is not authoritative, so deletion is disabled for that run. Run a plain sync (no recency filter) to reconcile deletions.

A run stopped saying the manifest or lineage store is corrupt

rs-suno refuses to run against a damaged .suno-manifest.json or .suno-lineage.json rather than risk re-downloading everything or losing archived lineage. Restore the file from a backup, or move it aside to start fresh. Starting fresh re-downloads every file: without the manifest there is no recorded digest to verify existing files against, so the safe choice is to re-fetch rather than trust unverified local copies.

A song I moved or renamed by hand came back, and the moved copy is still there

rs-suno tracks each file at the exact path it wrote. If you move or rename a downloaded file by hand, the next sync/copy sees nothing at the recorded path and downloads the clip again, leaving your moved copy in place as an untracked file. It is not re-identified and adopted: the manifest holds no content fingerprint of the audio and the clip id is not embedded in the tags, so there is no safe way to match a moved file back to its clip, and guessing could attach the wrong audio to a clip. check and --dry-run list these untracked audio files under an “untracked audio file(s)” note so you can see them; move each back into place (matching the layout check would use) or delete it, then re-sync. Let the tool own the file layout to avoid this.

A song’s title changed only in letter case or accents, but the file was not renamed

When a clip’s title changes only by letter case (for example Foo to FOO) or by Unicode normalisation (an accented character written a different but equivalent way), rs-suno intentionally keeps the existing file name. It treats two paths that differ only by case or normalisation as the same path, because that is how the Windows and macOS filesystems treat them, and the same rule underpins deletion safety so a rename can never clobber a protected clip. The engine does no disk IO and cannot safely tell whether your filesystem is case-sensitive, so it does not force a case-only rename that would be a no-op or a self-clobber on those platforms. On Linux or WSL2 the file keeps its earlier-case name, which is fully valid and openable.

FAQ

What is the difference between sync and copy?

sync mirrors, including deleting local files whose clips have left your library. copy only ever adds and updates. Use copy if you want an archive that never loses files.

I unliked a song (or it left my library) — what happens on the next sync?

Under sync it becomes a deletion candidate: once a clip is absent from every mirror source, its local file is removed (subject to the deletion-safety gates, so never on an empty, filtered, or failed listing). Under copy it is kept. Preview it first with check or --dry-run, which list the pending deletions.

How do I preview what a run would do?

Use check (or add --dry-run to sync/copy). Both report the pending changes without modifying the library. They scan managed files and may make read-only upstream requests so the plan matches a real run. check --exit-code exits 1 when verified changes are pending, 0 when verified up to date, and a partial or transient code when it cannot produce an authoritative plan.

Can I mirror more than one account?

Yes. Configure each account with its own token and root, then run --all to mirror every account into its own directory, or --account <label> for one. Account roots may not nest inside one another.

Does fetch need a config?

No. fetch can run with just --token (or SUNO_TOKEN). It downloads a single clip to a path you choose and never touches a mirrored library.

Where does my library go?

To the DEST you pass, or the account’s configured root. The config path itself is shown by suno version.

Which format should I choose?

FLAC (the default) is lossless and carries full metadata and embedded art. ALAC is lossless too and is the Apple-friendly choice (.m4a, plays natively on Apple devices and Apple Music), carrying the same tags and cover. MP3 is smaller and widely compatible. WAV is uncompressed and carries full ID3v2.4 metadata, including lyrics and embedded art, in a RIFF id3 chunk.

Why did a lossless run leave an MP3 in place?

Suno supplies FLAC and ALAC indirectly: suno downloads Suno’s authenticated WAV render, then converts it locally. A stale cookie or a paused, inactive, past-due, or non-entitled plan cannot request that WAV. suno never converts MP3 into a lossless container. If an MP3 already exists from an older run, it is kept for playback while the upgrade fails and the run returns non-zero. Once a verified FLAC or ALAC is committed, the MP3 is removed. A new lossless target does not fall back to MP3.

Why is a playlist track permanently MP3?

Suno restricts WAV conversion to the account recorded as the clip owner. A liked, shared, remixed, or covered track can retain another account’s user_id even when its display name looks familiar. rs-suno uses native MP3 for those non-owned clips and reports a note instead of repeatedly calling an endpoint that will always return 403. If a non-owned lossless file already exists, it is kept.

Is it safe to run on a schedule?

Yes. Runs are incremental and resumable, an exclusive lock prevents overlap, and the deletion safety rules prevent a bad listing from wiping files. See Scheduling and exit codes.