26.04 (Halfmoon) Development Notes

TrueNAS 26.04 (Halfmoon) is currently in active development.

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.

• 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 unexpected behavior such as SMB share failures after an upgrade.

  SSH auxiliary parameters are unsupported. Certain configurations can prevent the SSH service from starting.

TrueNAS Apps

Application maintenance, including version updates, features, and configuration options, is independent from TrueNAS version release cycles.
See documentation and resources at the TrueNAS Apps Market and the truenas/apps repository issues tracker 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.

Upgrading to TrueNAS 26.04 (Halfmoon) from an earlier TrueNAS release is primarily done using the web interface update process.

Another upgrade option is to use a TrueNAS .iso file to perform a fresh install on the system and then restore a system configuration file.

Update to the latest maintenance release of the current major version before upgrading to the next major version. You can then upgrade directly from the latest maintenance release to the latest release of the next major version.

This chart shows the basic upgrade paths between TrueNAS major versions. Depending on your use case and risk tolerance, you may prefer to delay upgrading to allow additional time for testing and stability. See the TrueNAS Software Status for version recommendations tailored to different user types 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.8 / 13.3-U2"]
              C -->|update| G
              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.4 (Electric Eel)"] -->|update| I
              I["25.04.2.4 (Fangtooth)"] -->|"(anticipated)"| J
            J["25.10 (Goldeye)"]
            

‹ ›

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

Permitted upgrade methods are:

• update: Apply updates using the Update screen in the TrueNAS UI or install a manual update file. Not all upgrade paths support automatic updates (see chart).
• ISO install: Save your TrueNAS configuration file, perform a fresh install using an .iso file for the target version, then upload the saved configuration.

You can skip major versions using a fresh installation with configuration file restore. Before skipping versions, review release notes for each major version to identify service deprecations or significant changes that may affect your configuration. Consider upgrading incrementally through major versions with significant changes, or be prepared to manually reconfigure any incompatibilities after upgrading directly to the target version.

Migrating TrueNAS from FreeBSD- to Linux-based versions is a one-way operation. Attempting to activate or roll back to a FreeBSD-based TrueNAS boot environment can break the system.

Upgrade your FreeBSD-based TrueNAS system to the latest publicly-available release version, 13.0-U6.7 (or 13.3-U1.2 for community users), before attempting to migrate. See Software Releases for current recommended update paths to make sure you download and migrate to the correct version.