Troubleshooting

“A start timestamp is required when the target has no existing scrobbles”

The default start comes from the target's latest event. An empty target has no value to infer. Supply a non-negative Unix timestamp:

syncfm sync --source source --target target --start 1704067200

“Unfinished work exists”

The CLI permits only one unfinished session per selected database:

syncfm status
syncfm resume SESSION_ID

If the work is no longer wanted, use syncfm discard SESSION_ID. Discard does not undo remote submissions.

Resume says profiles or networks do not match

Use the same direction, accounts, and profiles as the original run. Current sessions store profile names, so normally run only:

syncfm resume SESSION_ID

For a legacy session, provide both original names once. Confirm that the profile still points to the original username and service.

Profile credentials are missing

For keyring profiles, verify that the same OS user and keyring backend are available. Containers, SSH sessions, and desktop sessions can expose different keyrings. Re-create the profile with --force, or use an intentionally protected file-backed profile where a keyring cannot be provisioned.

Keyring operation fails

Install and unlock a backend supported by Python keyring. On headless systems, choose an appropriate backend explicitly or use --secret-storage file and protect the TOML file and its backups.

Configuration file is invalid

The file must be TOML with integer version = 1 and a [profiles] table. Keyring profiles must not include inline credential fields. File profiles must include an API secret and either password or session key. Use syncfm --config PATH profile list to validate a selected file.

GNU.fm hostname is rejected

Pass only the hostname:

music.example.org

Do not include https://, a path, user information, or whitespace.

Proxy URL is rejected

Use http, https, socks5, or socks5h, with a hostname and optional valid port. Remove paths, queries, and fragments. A scheme-less host:port value is treated as SOCKS5.

Authentication fails

Check username, API key, API secret, and password/session key against the selected service. API credentials from one service may not be valid on another. Replacing a profile requires --force.

A transient operation keeps failing

The default per-track policy makes three attempts five seconds apart, then raises RetryExhaustedError. Fix connectivity or proxy settings and resume. Snapshot fetch and resume reconciliation do not use this retry wrapper, so rerun resume after a transient failure there.

Post-sync verification has a separate timing policy. It checks the target up to three times, two seconds apart, when submitted scrobbles are not yet visible. A network exception during verification is not retried internally; run resume SESSION_ID to repeat verification. Because submission already completed, resume does not submit the queue again.

Verification is incomplete

An incomplete result means fresh source occurrences were still absent from the target after three checks. The CLI lists those events and offers to synchronize the same range again. Declining is not an error, and completed local recovery state has already been deleted.

Before retrying repeatedly, confirm that the target accepts historical timestamps and inspect whether it normalizes artist or title text. Verification uses exact artist, title, and timestamp identity and counts duplicate occurrences separately.

SQLite is locked or unavailable

Ensure the database parent directory is writable, only intended processes use the file, and the filesystem supports SQLite locking. Connections wait up to five seconds for a lock. Use separate database files for independent workloads.

A track was duplicated or missed

Initial comparison identity is exact artist, title, and Unix timestamp. Album is ignored. Differences in spelling or case are distinct; duplicate rows with the same three fields collapse in stored snapshots. Fresh post-sync verification uses the same identity but preserves duplicate occurrence counts. Inspect the two services' data within the exact inclusive range before retrying.

Get diagnostic output

Place --verbose before the command:

syncfm --verbose resume SESSION_ID

The CLI prints application-owned errors without a traceback in normal mode and enables diagnostic logging in verbose mode.