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.