TrueNAS 26 Development Notes

This section tracks features removed in 26 and features deprecated in 26 for future removal. Plan migrations immediately to avoid disruptions during upgrades.

The TrueNAS REST API has been fully replaced by the versioned JSON-RPC 2.0 Websocket API.

Migration Path:

1. Review current API integrations and identify all REST API calls.
2. Review the Websocket API documentation to identify replacement endpoints.
3. Update all scripts and integrations to use Websocket API endpoints.
4. Test thoroughly in a non-production environment.
5. Deploy updated integrations before upgrading to 26.

Impact: Systems still using the REST API must migrate to the Websocket API before upgrading to 26. REST API endpoints do not function in 26 and later.

See Also:

• Websocket API Documentation
• Managing API Keys

No features are currently deprecated for future removal.

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.

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| J
              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.6 (Fangtooth)"] -->|update| J
              J["25.10.2.1 (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.6 (Fangtooth)"] -->|update| H
              H["25.10.2.1 (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 might 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.