Table of contents
- Troubleshooting
- “A start timestamp is required when the target has no existing scrobbles”
- “Unfinished work exists”
- Resume says profiles or networks do not match
- Profile credentials are missing
- Keyring operation fails
- Configuration file is invalid
- GNU.fm hostname is rejected
- Proxy URL is rejected
- Authentication fails
- A transient operation keeps failing
- SQLite is locked or unavailable
- A track was duplicated or missed
- Get diagnostic output
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.
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
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. 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.