How Does Jellyfin Discover and Reconcile Changes Across Devices?
Jellyfin reconciles most cross-device changes through a central server, which discovers library updates, commits shared state, and serves the resulting view to clients.
A phone, television, browser, and tablet do not normally negotiate media-library truth directly with one another. They talk to the same Jellyfin server, which owns indexed library metadata and per-user state such as watch progress. Filesystem discovery, playback updates, and client refreshes are separate stages that converge on one server-side authority, so devices usually agree after the server accepts the change and each client refreshes.
The Server Is the Shared Authority, Not the Individual Clients
Clients render library views and send user actions, but the durable shared catalog lives on the server. That architecture lets a television and a phone see the same item without copying the entire database between devices. Each client can cache presentation state, yet the authoritative record for library membership and user progress remains centralized.
A media server is normally the authority for what is actually available and what played under its local users. A useful source-of-truth model treats the media server for playback as distinct from portable tracking systems. That same direction explains Jellyfin clients: they converge on server state instead of choosing a winner among peer devices.
This model simplifies conflict ownership because there is one place where accepted changes become durable. A client may temporarily display stale cached data, but it does not become a second equal database merely because it has not refreshed yet. Reconciliation means returning the client view to the server’s accepted state.
Filesystem Changes Become Library State Through Server-Side Discovery
Adding, replacing, renaming, or removing a media file first changes storage, not the Jellyfin catalog. The server must discover that filesystem event through a scan, monitoring trigger, or automation signal, inspect the affected path, and update its indexed representation. Only after that commit can clients receive the new library view.
Targeted automation tools such as targeted library updates exist because discovery can be triggered more precisely than waiting for a broad scheduled scan. The architectural point is unchanged: a file event becomes a server-side library update before it becomes a cross-device UI change.
This separates storage truth from catalog truth during the discovery window. A file can exist on disk while clients still do not see it, or an indexed item can remain briefly until removal is processed. Measuring the time from filesystem change to server index update is therefore different from measuring how quickly a client refreshes after the server has already committed the change.
Playback Progress Returns to the Same Server-Side User State
Watch progress follows a different input path from filesystem discovery. The media file does not change when a viewer reaches minute forty; the client reports playback state associated with the authenticated user, and the server records that user-specific update. Another device logged into the same account can later query the shared server state and resume from the accepted position.
This is why Jellyfin can watch history syncs across devices across clients without copying a local progress file directly between the television and phone. Both devices converge because they read and write through the same user record on the server, not because they perform peer-to-peer reconciliation.
The observable boundary is write timing. If a device goes offline before its progress update reaches the server, another device can legitimately show the older server value. Once connectivity returns, the final result depends on which update the application accepts and in what order. Offline local progress should not be mistaken for already committed shared state.
Clients Reconcile by Refreshing From the Server, Not by Merging With Each Other
After the server commits a change, clients still need a refresh, event, navigation action, or subsequent request that retrieves the new state. A television may keep a stale poster grid in memory while a browser already shows the update. That temporary divergence is a presentation-cache issue unless the server itself contains conflicting records.
Client diversity makes this distinction visible because different Jellyfin clients can present the same server with different interfaces and playback behavior. If one client looks stale while another is current, verify server state first, then refresh or reconnect the outlier before treating the mismatch as a database conflict.
This distinction matters during debugging. If two clients disagree, query or inspect the server state first. If the server has the expected value and only one client is stale, refresh or cache behavior is the likely boundary. If the server itself lacks the update, investigate discovery, permissions, or the write event before blaming the second client.
Failure Boundary: Separate Servers Do Not Automatically Reconcile Their Databases
The central-authority model applies inside one Jellyfin server instance. If a household runs two independent servers, each can accumulate its own users, watch state, metadata edits, and library database changes. There is no general assumption that those databases will discover each other and merge safely merely because they point at similar media files.
Cross-server tools such as explicit watch-state synchronization exist precisely because independent media servers need an explicit reconciliation mechanism for shared progress. That tool can synchronize a defined subset of state; it does not turn two complete Jellyfin databases into a transparent multi-master cluster.
The same boundary applies to offline devices. A client can retain a stale local view, but it should not be treated as an authoritative database to merge manually into Jellyfin. When multiple writers or servers are introduced, define which state is authoritative, which fields are synchronized, and how conflicting updates are resolved before calling the design “reconciled.”
Run a Four-Step Reconciliation Test Across Two Devices
Use two clients logged into the same test user and one known media item. First add or rename a test file and time the server’s discovery. Second confirm both clients receive the new catalog state after refresh. Third change watch progress on client A and confirm client B receives the accepted server value. Fourth restart the server and verify the committed state survives.
The internal explanation of concurrent state consistency provides the complementary database boundary: accepted writes need transaction and ordering rules so overlapping activity does not expose half-finished updates. The cross-device test adds discovery and client-refresh timing on top of that persistent-state guarantee.
Pass only when the server becomes the same observable authority after each step: storage changes are indexed once, both clients converge on the same library result, user progress is not duplicated or lost, and restart does not revert a committed update. If disagreement remains, identify whether the break occurred at discovery, server commit, client refresh, or a separate-server boundary.
FAQ
Do Jellyfin clients sync directly with each other?
Normally no. A phone, television, browser, and tablet converge through the Jellyfin server: clients send updates to the server and later read server state. Treating clients as peer replicas makes ordinary refresh delays look like conflicts that do not actually exist.
Why can one Jellyfin client show stale library data?
The server may already have committed a library or playback change while one client still shows an older cached view. Confirm the server-side state from another client or the web interface, then refresh or reconnect the outlier before investigating discovery or database problems.
Can two separate Jellyfin servers automatically sync watch progress?
Separate Jellyfin servers do not form an automatic multi-master state system. If the same user must carry watch history between independent servers, use an explicit synchronization workflow with a defined source of truth and test conflict behavior before relying on it.
Recommended products
Tech & AI HUB
More to Read
How Does Backup Frequency Affect Jellyfin Recovery Point Quality?
Shorter backup intervals can reduce Jellyfin state loss, but recovery point quality also depends on coherent capture, retention history, and tested restores.
What Is a Safe Jellyfin Upgrade Boundary, and Why Does It Matter?
Safe Jellyfin upgrades keep the runtime and persistent state recoverably paired, because reverting an image does not reverse schema, data, or plugin changes.
What Causes Jellyfin to Retain More Temporary Data Than Expected?
Temporary Jellyfin data has different owners and lifecycles; diagnose retention by creator, reuse value, and the cleanup trigger that should remove it.
