Immich Time Zone Bug: EXIF OffsetTime Issue & Fixes

by Omar Yusuf 52 views

#table of contents

Hey guys! Are you experiencing time zone issues with your photos in Immich? You're not alone! This article dives deep into a tricky bug where Immich, the awesome open-source photo management solution, sometimes gets the time zone wrong. We'll break down why this happens, especially for those of you using software like Adobe Lightroom or Photoshop. We'll walk through the technical details, show you how to reproduce the issue, and discuss potential solutions and workarounds. Our main goal is to ensure your precious memories are accurately time-stamped within Immich. So, let's explore this time zone discrepancy and get your photos back on track! Understanding the nuances of how EXIF data is handled, especially the difference between EXIF:OffsetTime and EXIF:OffsetTimeOriginal, is crucial. These tags store time zone information, and Immich's current prioritization of EXIF:OffsetTime can lead to misinterpretations when software like Photoshop modifies this tag during image export. This article will serve as a comprehensive guide, providing detailed steps to identify, reproduce, and potentially resolve this issue, ensuring accurate time zone representation for your photos in Immich.

The core of the issue lies in how Immich handles EXIF data, specifically the EXIF:OffsetTime and EXIF:OffsetTimeOriginal tags. The bug report highlights that Immich incorrectly prioritizes EXIF:OffsetTime when determining the time zone of an image. For those unfamiliar, EXIF (Exchangeable Image File Format) data is metadata embedded within image files, containing information such as date, time, camera settings, and, crucially, time zone offsets. EXIF:OffsetTime is intended to represent the time zone offset at the time of the file's modification, while EXIF:OffsetTimeOriginal reflects the time zone offset at the time the photo was taken. Programs like Adobe Lightroom and Photoshop often update EXIF:OffsetTime to match the file's modification date, which can differ significantly from the photo's original capture time. Consequently, Immich, by relying on EXIF:OffsetTime, ends up assigning an incorrect time zone to the image. This misinterpretation can lead to photos being displayed in the wrong order, appearing on the wrong date in timelines, and generally causing confusion in your photo library. This is particularly frustrating because the correct time zone information is often present in the EXIF:OffsetTimeOriginal tag, but Immich isn't utilizing it. This issue impacts users who rely on professional photo editing workflows, where images are frequently modified and re-exported. The reliance on EXIF:OffsetTime over EXIF:OffsetTimeOriginal leads to a discrepancy between the intended capture time and the time displayed in Immich, potentially disrupting the chronological organization of your photo library. This behavior contradicts the expected functionality, where the original capture time should be the primary determinant for time zone assignment. Therefore, addressing this bug is crucial to ensuring accurate and reliable photo management within Immich.

To really understand what's going on, let's dive into the technical side. We'll walk through the steps to reproduce this bug and analyze the EXIF data involved. This will help you see exactly how Immich is misinterpreting the time zone information. This section provides a detailed, step-by-step guide to reproduce the time zone bug in Immich, allowing users to verify the issue firsthand and understand the underlying EXIF data discrepancies. By following these steps, you can observe how Immich incorrectly prioritizes EXIF:OffsetTime over EXIF:OffsetTimeOriginal, leading to inaccurate time zone assignments. The analysis of the EXIF data using exiftool provides a clear view of the time zone offsets stored in different tags and how they are interpreted by Immich. This technical deep dive is crucial for developers and advanced users to grasp the root cause of the problem and contribute to its resolution. Understanding the exact steps to reproduce the bug and the corresponding EXIF data changes is essential for effective debugging and testing of potential fixes. Let's explore each step with detailed instructions and clear examples.

First, let's start with an original Nikon RAW file. This file has the correct time zone information embedded in its EXIF data. When you upload this file to Immich, it should display the correct time. We'll use exiftool, a powerful command-line tool for reading and writing metadata, to inspect the file's EXIF data.

exiftool -time:all -a -G0:1 -s DSC_3701.NEF

This command will output all time-related EXIF tags, including OffsetTime, OffsetTimeOriginal, and DateTimeOriginal. Notice that all these tags have the correct time zone offset (+01:00 in this example). When this file is uploaded to Immich, it correctly displays the time as 23:39 UTC+1. This baseline ensures that the original file contains the correct time zone information, allowing us to compare it with the modified file in the subsequent steps. The consistency in the time zone information across different EXIF tags in the original RAW file highlights the importance of preserving this data during editing and export processes. This step is crucial for establishing a control case, demonstrating that Immich can correctly interpret time zones when the EXIF data is consistent and accurate. The detailed EXIF data analysis provides a clear picture of the time zone information present in the original file, setting the stage for understanding how this information can be altered during image processing.

Now, let's export the same RAW file from Photoshop as a JPG. This is where the problem starts. Photoshop, and similar software, often updates the EXIF:OffsetTime tag to reflect the file's modification time, not the original capture time. This is a crucial step in reproducing the bug. When a RAW file is processed and exported via Photoshop, the EXIF:OffsetTime can be modified to match the current time zone of the system or the time zone at the time of export. This change, while seemingly minor, has significant implications for applications like Immich that rely on this tag for time zone determination. By exporting the file to JPG, we create a scenario where the EXIF:OffsetTime and EXIF:OffsetTimeOriginal tags contain different time zone information. The EXIF:OffsetTime will reflect the time zone during export (e.g., +08:00), while EXIF:OffsetTimeOriginal retains the original capture time zone (e.g., +01:00). This discrepancy is the key to triggering the bug in Immich. Uploading this modified JPG file to Immich will then demonstrate the issue, as Immich will prioritize the incorrect EXIF:OffsetTime over the correct EXIF:OffsetTimeOriginal. The exported JPG file serves as a practical example of how common image editing workflows can introduce time zone inconsistencies, highlighting the need for robust time zone handling in photo management systems like Immich. This step is essential for understanding the real-world impact of the bug and for developing effective solutions.

Let's analyze the EXIF data of the exported JPG using exiftool again:

exiftool -time:all -a -G0:1 -s test.jpg

Notice that EXIF:OffsetTime is now +08:00, while EXIF:OffsetTimeOriginal remains +01:00. This discrepancy is the root of the problem. When you upload this JPG to Immich, it incorrectly displays the time as 06:39 UTC+8 instead of the correct 23:39 UTC+1. This incorrect time zone assignment clearly demonstrates the bug in action, where Immich prioritizes EXIF:OffsetTime over EXIF:OffsetTimeOriginal. The EXIF data analysis reveals the exact changes made during the export process, providing a concrete example of how the time zone information is altered. This step is critical for visualizing the issue and understanding the specific EXIF tags involved. The discrepancy between EXIF:OffsetTime and EXIF:OffsetTimeOriginal is the key indicator of the bug, making it essential to analyze these tags when troubleshooting time zone issues in Immich.

Thankfully, there's a workaround! We can manually correct the EXIF:OffsetTime tag using exiftool. This will force Immich to recognize the correct time zone. To fix the time zone, we can use the following command:

exiftool -time:all -OffsetTime=+01:00 -o test_mod.jpg test.jpg

This command sets the EXIF:OffsetTime tag to +01:00, matching the EXIF:OffsetTimeOriginal. Now, let's inspect the modified file:

exiftool -time:all -a -G0:1 -s test_mod.jpg

You'll see that both EXIF:OffsetTime and EXIF:OffsetTimeOriginal are now +01:00. Uploading this corrected JPG to Immich will display the correct time: 23:39 UTC+1. This workaround demonstrates that Immich can correctly interpret the time zone when EXIF:OffsetTime is accurate. The manual correction highlights the importance of EXIF data integrity and the impact of specific tags on Immich's time zone interpretation. This step provides a practical solution for users facing this issue and reinforces the need for Immich to prioritize EXIF:OffsetTimeOriginal or implement a more robust time zone detection mechanism. The successful correction of the time zone through manual EXIF data modification underscores the importance of addressing this bug in Immich to prevent future inconsistencies. This workaround, while effective, is not ideal for large photo libraries, making a proper fix within Immich crucial for a seamless user experience.

This bug might seem minor, but it can have a significant impact on your photo library organization. Imagine your photos scattered across your timeline, appearing on the wrong dates! It makes it difficult to relive memories chronologically. The time zone discrepancy issue in Immich can disrupt the chronological organization of your photo library, making it challenging to navigate and relive memories in the correct sequence. When photos are assigned incorrect time zones, they appear out of order in timelines and albums, leading to a fragmented and confusing user experience. This issue is particularly problematic for users who travel frequently or work with images from multiple sources, as the time zone metadata becomes crucial for accurate sorting and display. The impact extends beyond mere inconvenience; it can affect the perceived value and usability of a photo management system. If Immich cannot reliably display photos in the correct order, users may lose trust in the platform and seek alternative solutions. Addressing this bug is therefore essential for maintaining the integrity of the user's photo collection and ensuring a seamless and enjoyable experience. The accuracy of time zone information is also critical for features such as map-based photo browsing and event-based organization, where photos taken at the same time and location should be grouped together. This bug can undermine these features, diminishing the overall functionality and appeal of Immich. Therefore, resolving the time zone issue is not just about fixing a technical glitch; it's about upholding the core promise of a photo management system: to preserve and present memories in a meaningful and accurate way.

Let's take a look at the technical environment where this bug was observed. The user reported running Immich Server on a Synology NAS using Docker. This setup is quite common, so understanding the configuration is crucial for troubleshooting. The fact that the issue was observed on a Synology NAS using Docker highlights the potential for widespread impact, as this is a popular deployment method for Immich users. Docker containers provide a consistent environment across different systems, meaning that a bug occurring in this setup is likely to affect other users with similar configurations. The Synology NAS environment introduces specific considerations, such as file system permissions, storage configurations, and Docker networking, which can influence how Immich interacts with EXIF data. Understanding these factors is essential for diagnosing the root cause of the bug and developing effective solutions. The system configuration, including the operating system, Docker version, and underlying hardware, can all play a role in how Immich processes and interprets EXIF data. Therefore, providing detailed information about the environment is crucial for developers to accurately reproduce the issue and identify potential compatibility problems. The user's environment also includes specific versions of Immich Server and the Immich Mobile App, which are important for tracking down the bug to a particular release or set of releases. This information helps narrow down the scope of the problem and focus debugging efforts on the relevant code changes and dependencies.

Here's the docker-compose.yml file used in the bug report. This file defines the services and configurations for running Immich in Docker. Analyzing this configuration can give us clues about potential issues. The docker-compose.yml file is a critical piece of information for understanding how Immich is deployed and configured in the user's environment. This file defines the different services that make up the Immich application, including the server, machine learning components, Redis, and PostgreSQL database. By examining the docker-compose.yml, we can identify potential issues related to networking, volume mounts, environment variables, and dependencies between services. For example, the volume mounts define where Immich stores its data, and incorrect configurations can lead to data loss or access problems. The environment variables specify settings such as database credentials and time zone information, which can directly impact the time zone bug. The dependencies between services ensure that the database and Redis are running before the Immich server starts, preventing startup errors. The docker-compose.yml also includes health checks for each service, which are used to monitor the application's status and restart containers if they fail. These health checks are essential for ensuring the reliability and availability of Immich. By carefully analyzing the docker-compose.yml, we can gain insights into the user's setup and identify potential areas of misconfiguration or compatibility issues that might be contributing to the time zone bug. This file serves as a comprehensive blueprint of the Immich deployment, making it an invaluable resource for debugging and troubleshooting.

#
# WARNING: To install Immich, follow our guide: https://immich.app/docs/install/docker-compose
#
# Make sure to use the docker-compose.yml of the current release:
#
# https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
#
# The compose file on main may not be compatible with the latest release.

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    # extends:
    #   file: hwaccel.transcoding.yml
    #   service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
    volumes:
      # Do not edit the next line. If you want to change the media storage location on your system, edit the value of UPLOAD_LOCATION in the .env file
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
      # - /volume1/docker/immich/geodata:/build/geodata
      # - /volume1/docker/immich/i18n-iso-countries/langs:/usr/src/app/server/node_modules/i18n-iso-countries/langs
    env_file:
      - .env
    ports:
      - '2283:2283'
    depends_on:
      - redis
      - database
    restart: always
    healthcheck:
      disable: false

  immich-machine-learning:
    container_name: immich_machine_learning
    # For hardware acceleration, add one of -[armnn, cuda, rocm, openvino, rknn] to the image tag.
    # Example tag: ${IMMICH_VERSION:-release}-cuda
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    # extends: # uncomment this section for hardware acceleration - see https://immich.app/docs/features/ml-hardware-acceleration
    #   file: hwaccel.ml.yml
    #   service: cpu # set to one of [armnn, cuda, rocm, openvino, openvino-wsl, rknn] for accelerated inference - use the `-wsl` version for WSL2 where applicable
    volumes:
      - ${CACHE_LOCATION}:/cache
    env_file:
      - .env
    restart: always
    healthcheck:
      disable: false

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:8-bookworm@sha256:facc1d2c3462975c34e10fccb167bfa92b0e0dbd992fc282c29a61c3243afb11
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:32324a2f41df5de9efe1af166b7008c3f55646f8d0e00d9550c16c9822366b4a
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
      # Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
      # DB_STORAGE_TYPE: 'HDD'
    volumes:
      # Do not edit the next line. If you want to change the database storage location on your system, edit the value of DB_DATA_LOCATION in the .env file
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    shm_size: 128mb
    restart: always

volumes:
  model-cache:

The .env file contains environment variables used by the Docker containers. The time zone setting (TZ) is particularly relevant to this bug. The .env file is a crucial configuration component in the Immich deployment, as it stores environment variables that control various aspects of the application's behavior. Analyzing the contents of this file, especially the TZ variable, is essential for understanding the time zone context in which Immich is running. The TZ variable specifies the time zone that the Immich server and other components will use. If this variable is not set correctly or is inconsistent with the time zone information in the EXIF data, it can contribute to the time zone bug. The .env file also contains other important settings, such as database credentials, upload locations, and cache locations. These settings can indirectly affect the time zone behavior of Immich, as they influence how the application interacts with files and metadata. For example, the UPLOAD_LOCATION variable determines where Immich stores the uploaded photos, and the file system's time zone settings can potentially impact how the file modification times are interpreted. By examining the .env file, we can ensure that the time zone settings are correctly configured and that there are no conflicting or missing variables that might be contributing to the bug. This file provides a centralized view of the application's environment, making it a valuable resource for troubleshooting and configuration management. Understanding the role of the .env file and its contents is essential for maintaining a stable and accurate Immich deployment.

# You can find documentation for all the supported env variables at https://immich.app/docs/install/environment-variables

# The location where your uploaded files are stored
UPLOAD_LOCATION=/volume1/docker/immich/photo

# The location where your database files are stored. Network shares are not supported for the database
DB_DATA_LOCATION=/volume1/docker/immich/data

CACHE_LOCATION=/volume1/docker/immich/cache

# To set a timezone, uncomment the next line and change Etc/UTC to a TZ identifier from this list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
TZ=Asia/Shanghai

# The Immich version to use. You can pin this to a specific version like "v1.71.0"
IMMICH_VERSION=release

# Connection secret for postgres. You should change it to a random password
# Please use only the characters `A-Za-z0-9`, without special characters or spaces
DB_PASSWORD=postgres

# The values below this line do not need to be changed
###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

So, what can be done about this? Here are a few ideas:

  • Prioritize EXIF:OffsetTimeOriginal: The ideal solution is for Immich to prioritize EXIF:OffsetTimeOriginal over EXIF:OffsetTime when determining the time zone. This would ensure that the original capture time zone is used, even if EXIF:OffsetTime has been modified.
  • Provide a configuration option: Another approach is to provide a configuration option that allows users to choose which EXIF tag Immich uses for time zone determination. This would give users more control over how their photos are displayed.
  • Manual Correction: As demonstrated earlier, you can use exiftool to manually correct the EXIF:OffsetTime tag. This is a viable workaround for individual files or small batches, but it's not practical for large photo libraries. Addressing the time zone bug in Immich requires a multi-faceted approach, combining immediate workarounds with long-term solutions. Prioritizing EXIF:OffsetTimeOriginal over EXIF:OffsetTime is the most direct way to resolve the issue, as it ensures that the original capture time zone is used for display. This approach aligns with the expected behavior of a photo management system, where the creation time should be the primary determinant of the time zone. Providing a configuration option for users to choose the EXIF tag for time zone determination offers greater flexibility and caters to different workflows. Some users may prefer to use EXIF:OffsetTime in specific scenarios, and this option allows them to customize Immich's behavior accordingly. The manual correction workaround using exiftool is a valuable tool for users who need to fix individual files or small sets of photos. While not a scalable solution for large libraries, it provides immediate relief for critical cases. In the long term, Immich could also implement a more intelligent time zone detection mechanism that considers multiple EXIF tags and other metadata to determine the most accurate time zone. This approach would reduce the reliance on a single tag and improve the robustness of the system. Furthermore, Immich could provide tools within the application to help users identify and correct time zone discrepancies, making it easier to manage their photo libraries. By combining these solutions, Immich can address the time zone bug effectively and provide a more reliable and user-friendly experience.

This bug report highlights the importance of community contributions in open-source projects like Immich. User feedback and detailed bug reports are invaluable for identifying and fixing issues. The Immich community plays a vital role in the project's success by providing feedback, reporting bugs, and contributing code. This bug report exemplifies the importance of user contributions in identifying and addressing issues that might otherwise go unnoticed. The detailed information provided in the report, including the reproduction steps, EXIF data analysis, and system configuration, is invaluable for developers to understand the problem and develop effective solutions. Community discussions around bug reports and feature requests help prioritize development efforts and ensure that Immich meets the needs of its users. By sharing their experiences and insights, community members contribute to a collective understanding of the application's strengths and weaknesses. Open-source projects thrive on collaboration, and contributions can take many forms, from reporting bugs and suggesting improvements to writing code and documentation. The Immich community's active participation is essential for the project's growth and evolution. Encouraging community contributions and providing clear channels for communication and feedback are crucial for fostering a vibrant and engaged community. Bug reports like this one serve as a catalyst for discussion and collaboration, leading to improved software quality and a more user-centric development process. The open-source nature of Immich allows users to not only report issues but also propose and implement solutions, further empowering the community to shape the project's future. This collaborative approach is a key strength of open-source software and a driving force behind Immich's ongoing development.

The time zone bug in Immich, while seemingly small, can have a big impact on how you experience your photo library. By understanding the issue and the EXIF data involved, we can work towards a solution. Whether it's prioritizing EXIF:OffsetTimeOriginal or providing configuration options, addressing this bug will make Immich an even better photo management solution. We've explored the intricacies of the time zone bug in Immich, highlighting the importance of accurate EXIF data interpretation for a seamless photo management experience. The discrepancy between EXIF:OffsetTime and EXIF:OffsetTimeOriginal can lead to significant organizational issues, disrupting the chronological flow of your memories. Addressing this bug is crucial for maintaining the integrity and usability of Immich, ensuring that your photos are displayed in the correct order and time zone. The solutions discussed, including prioritizing EXIF:OffsetTimeOriginal and providing user configuration options, offer a path forward for resolving this issue. By implementing these changes, Immich can provide a more reliable and user-friendly experience, catering to the diverse needs of its user base. Community contributions and discussions play a vital role in driving these improvements, fostering a collaborative environment where users and developers work together to enhance the software. The open-source nature of Immich empowers the community to shape the project's future, ensuring that it continues to evolve and meet the challenges of modern photo management. As Immich continues to develop, addressing issues like the time zone bug will be essential for solidifying its position as a leading open-source photo management solution. The commitment to accuracy and user experience will drive Immich's success, making it an indispensable tool for preserving and reliving your precious memories. Let's hope this bug gets squashed soon, so we can all enjoy our photos in their proper time! Stay tuned for updates, and keep contributing to the Immich community!