25.10 (Goldeye) Development Notes

25.10 (Goldeye) will bring many new features and improvements to the TrueNAS experience.

Check back for more information.

Early releases of a major version are intended for testing and feedback purposes only. Do not use early release software for critical tasks.

The release names and dates provided here are tentative and can change at any time.

• TrueNAS is an appliance built from specific Linux packages. Updating TrueNAS using apt or any method other than the TrueNAS web interface can make the system inoperable.

• Modifying the base OS can cause unexpected behavior during upgrades:

  Users who manually installed Docker on TrueNAS 24.04 or earlier can experience TrueNAS Apps failure in 24.10 or later.

  This occurs due to conflicts between the manually installed and native Docker configurations.

  • Affected systems can encounter app_lifecycle.compose_action errors, such as:
    'group_add[0]' expected type 'string', got unconvertible type 'int', value: '568'
  • See NAS-134660 for details and a workaround.

• All auxiliary parameters can experience changes between TrueNAS major versions due to security and development changes. We recommend removing all auxiliary parameters from TrueNAS configurations before upgrading as these settings can result in SMB share failures after an upgrade.

The TrueNAS REST API is deprecated starting in TrueNAS 25.04. Full removal of the REST API is planned for a future release.

The chart below shows recommended paths for upgrading from earlier TrueNAS versions.

Update the system to the latest maintenance release of the installed major version before attempting to upgrade to a new major version.

Permitted upgrade methods are:

• update: apply an automatic update using the Update screen in the TrueNAS UI or install a manual update file. Some upgrade paths do not support these options (see chart).
• ISO install: save a current TrueNAS configuration file, perform a fresh install using an .iso file for the target version, and then upload the previously saved configuration.

Users can skip major versions with a fresh ISO install followed by a configuration file upload. Carefully review release notes for each skipped major version before upgrading, noting any service deprecations or significant changes that impact the previous configuration. Consider stopping at major versions with significant impacts to address changes before continuing the upgrade path or be prepared to manually reconfigure incompatibilities on the latest target version.

This chart shows the basic update path to and from the latest release of each TrueNAS major version. Depending on your use case and risk tolerance, some users may prefer to remain on an earlier minor or major version for a period of time before updating. Visit the TrueNAS Software Status page for recommendations on which software version to use, tailored to user types ranging from Developer to Mission Critical.

          flowchart LR
            A["11.3-U5"] -->|update| B["12.0-U8.1"]
            B -->|"update

ISO install"| C["13.0-U6.4

13.3-U1"]
            C -->|ISO install| H
            C -->|ISO install| I
            D["22.02.4 (Angelfish)"] -->|update| E
            E["22.12.4.2 (Bluefin)"] -->|update| F
            F["23.10.2 (Cobia)"] -->|update| G
            G["24.04.2.5 (Dragonfish)"] -->|update| H
            H["24.10.2.1 (Electric Eel)"] -->|update| I
            I["25.04.0 (Fangtooth)"]
          

          flowchart LR
            A["11.3-U5"] -->|update| B
            B["12.0-U8.1"] -->|update| C
            C["13.0-U6.4"] -->|ISO install| F
            C["13.0-U6.4"] -->|"(anticipated)"| G
            D["23.10.2 (Cobia)"] -->|update| E
            E["24.04.2.5 (Dragonfish)"]  -->|update| F
            F["24.10.2.1 (Electric Eel)"] -->|"(anticipated)"| G
            G["25.04 (Fangtooth)"]