Fix Cannot Read Properties Of Undefined (Reading 'split') Immich Error

Hey guys! Today, we're diving deep into a common issue that Immich users have been running into: the dreaded "Cannot read properties of undefined (reading 'split')" error. This bug can be a real headache, especially when you're trying to access your timeline and all you see is an error message. Let's break down what causes this error, how to identify it, and most importantly, how to fix it. So, let’s get started and make sure your Immich experience is smooth sailing!

Understanding the Error

The "Cannot read properties of undefined (reading 'split')" error is a common JavaScript error that occurs when you try to call the split() method on a variable that is undefined. In simpler terms, it means the code is trying to split a value that doesn't exist. In the context of Immich, this usually happens when the application is trying to process data from the server, and a particular field or property is missing or null when it’s expected to be a string. Understanding this error message is crucial for any developer or user trying to troubleshoot issues within web applications, especially those dealing with data manipulation.

This error specifically points to a situation where a variable expected to hold a string value is instead holding an undefined value. The .split() method in JavaScript is used to divide a string into an ordered list of substrings, based on a specified separator, and returns an array. When this method is called on an undefined value, JavaScript throws a TypeError, because undefined does not have properties or methods, including split. This kind of error is common in web development, especially in applications that handle data fetched from APIs or databases, where the structure or the completeness of the data cannot always be guaranteed.

Why Does This Happen in Immich?

In Immich, this error often surfaces when the app is fetching and processing timeline data. The timeline view aggregates media assets, and the application needs to handle various data points like dates, durations, and locations. If any of these data points are missing or incorrectly formatted in the server's response, it can trigger the split() error. For example, if the duration field of a video asset is null instead of a time string, the code might try to split this null value, leading to the error. This situation can occur due to various reasons, such as issues during data migration, database inconsistencies, or bugs in the server-side code that handles data serialization.

Another common scenario is related to how Immich handles geographic data. If the city or country information for an asset is missing, the application might attempt to process these missing values, resulting in the same error. The application's reliance on specific data structures and the potential for inconsistencies in the stored data make it susceptible to this kind of error. Therefore, understanding the flow of data from the server to the client-side application is crucial for diagnosing and resolving this issue effectively.

Identifying the Root Cause

To really nail down what’s causing the problem, you’ve got to dig into the error message itself. The error typically looks something like this:

Uncaught TypeError: Cannot read properties of undefined (reading 'split')
    at Xr (B1LP_BB7.js:1:16803)
    at Bl2m2zqA.js:1:9030
    ...

This might seem like gibberish at first, but don't worry! The key part here is the line that says "Cannot read properties of undefined (reading 'split')". This tells you exactly what the problem is. The rest of the message shows you where in the code the error occurred, which can be super helpful for developers.

In the provided error log, the at Xr (B1LP_BB7.js:1:16803) and subsequent lines indicate the specific JavaScript files and line numbers where the error originated. While these file names are often obfuscated in production code (like B1LP_BB7.js), they provide a starting point for developers to trace the execution path and identify the exact function call that led to the error. The stack trace (the series of at lines) shows the sequence of function calls that were made before the error occurred, which is invaluable for understanding the context in which the error happened.

To further pinpoint the issue, checking the network requests made by the application can provide additional clues. In the bug report, the user mentioned a specific API endpoint: /api/timeline/bucket?timeBucket=2025-08-01T00%3A00%3A00.000Z&visibility=timeline&withPartners=true&withStacked=true. This request fetches the timeline data for a specific date. Examining the response from this endpoint (as the user did by including the JSON response) is critical for identifying malformed or missing data that could be causing the error. This approach combines the information from the error message with the data being processed, making it easier to understand the relationship between the code and the data, and ultimately, to resolve the issue.

Analyzing the JSON Response

The provided JSON response is a goldmine for figuring out this bug. When we dive into the data, we can see a few potential culprits in the duration array. This array contains strings representing the durations of video assets, but it also includes null values and even a `