What Changes in 3.0

Some 2.6 behaviour changes on purpose in 3.0. Use the table to find the changes that affect you, then read only those sections. upgrade check reports each of these for your own data before anything is changed.

To run the upgrade, go to Upgrade from 2.6.x to 3.0.

Find what affects you

Act before you upgrade. These cannot be undone afterwards.

Change	It affects you if	What to do
History is capped at 32 days	You keep more than 32 days of history	Export the history you need. The first start of 3.0 deletes the rest.
UNS topic paths include the organization	MQTT clients or other systems outside MaestroHub use UNS topic paths	Plan the new paths for each client.
The shared uns_reader MQTT login is gone	An MQTT subscriber signs in as uns_reader	Give each subscriber its own API client.
Knowledge model, schemas and alerts are rebuilt	You use schemas, asset instances or alert limits on 2.6	Note what you have: it is not carried over.
An expired license no longer falls back to the trial	A license was applied to this instance and has expired or will expire soon, or the instance is licensed by a Fleet Manager	Have a valid license key ready. Without one, pipelines stop after the upgrade.

Check after you upgrade. The upgrade handles these, and the report tells you what it did.

Change	It affects you if	What to do
Access changes are reported per user	Always	Read the access notes in the report.
Resources created on 2.6.0 may have no owner	You ever ran 2.6.0	Assign an owner to each resource the report names.
Secrets are now encrypted	Always	Keep the new key files with your data. Delete the backup set once 3.0 runs well.
Store locations follow one rule	You changed store locations in config.yaml, or use PostgreSQL	Delete the old location keys when convenient.
A read from a disconnected device now fails the run	Pipelines read from devices that go offline	Set On Error to continue where a pipeline should go on.
A script failure has its own error code	A pipeline compares error codes	Check the pipelines the report lists.
Connector behaviours that change on purpose	You use RabbitMQ publish, or FTP/SFTP rename	Read the note on each function the report lists.
The first start runs long database work	Your audit trail or execution history is large	Do not stop MaestroHub during the first start.
Image and command names	You use the maestrohub/lite image	Nothing now. Move to the new names when convenient.

History is capped at 32 days

3.0 keeps 1, 7, 14 or 32 days of history by default, for the built-in historian and for TimescaleDB. If 2.6 kept more, upgrade apply sets it to 32 days. This covers a retention over 32 days, a cold store kept forever, and a TimescaleDB retention of "keep forever". At the first 3.0 start, every value older than 32 days is deleted.

upgrade check tells you before anything is applied: the old value, the new value, and how much history the first start deletes. Export what you need first. The upgrade backup does not hold history.

The upgrade does not edit your config.yaml. If your config.yaml enables the cold store with a cold retention of 0 (forever) or more than 32 days, 3.0 refuses to start. The error names the setting to change.

UNS topic paths include the organization

In 3.0, every UNS topic path contains its organization: mHv1.0/test/line1 in the organization durable-goods becomes mHv1.0/durable-goods/test/line1. The upgrade rewrites topics, their history, dashboards, pipeline topic paths and access grants on topics. Topics keep their IDs.

Plan for what the upgrade cannot see:

• MQTT clients and systems outside MaestroHub that subscribe to or publish on UNS topic paths need the new paths.
• Retained messages and subscribers on an external broker are not changed. check reports them.
• Scripts that pick a topic segment by position may need a different position. check lists each one as needing a person, with the proposed change.
• If an organization has two topics that become the same path in 3.0, apply refuses. check names both topics. Rename or delete one on 2.6, where you know its MQTT consumers, then upgrade.

Store locations follow one rule

In 3.0, two settings decide where every store lives:

• storage.engine: sqlite (the default) or postgres.
• storage.dataDir: the folder for SQLite stores and other local files. Each store is <storage.dataDir>/<store>.db.

With postgres, one storage.postgres block names the server, and each store gets its own database, <store>_db.

• apply moves your stores. Stores that 2.6 kept elsewhere (next to the data folder, under an old name such as pipeline.db, or where your old config placed them) are moved to where 3.0 keeps them. check lists every move first. Stores on another volume need --copy-across-volumes (see Apply options).
• Per-store location keys in config.yaml are ignored now. Keys such as modules.<name>.storageType, modules.<name>.sqlite.path, a module's own postgres block, and the old secrets, NATS and historian path keys are not read. MaestroHub warns about each one at startup, naming the line to delete. Delete them when convenient. A read-only mounted 2.6 config still starts, with warnings.
• The upgrade does not move data between engines, with one exception, below. If a store is in SQLite and your 3.0 configuration places it in PostgreSQL, or the other way round, 3.0 refuses to start and apply refuses too.

UNS metadata and the historian are separate

The UNS metadata store holds topics, dashboards and UNS settings. It is an ordinary store and follows storage.engine like every other store. The historian holds your time-series values, in the built-in store or in TimescaleDB. It stays a runtime setting, chosen in the UNS settings, and does not change where the UNS metadata store lives.

2.6 could keep the UNS metadata store in PostgreSQL (modules.uns.storage in the 2.6 config.yaml) while every other store was in SQLite. With storage.engine: sqlite, apply copies that store's tables into <storage.dataDir>/uns.db and converts the copy. It only reads the PostgreSQL database and never writes to it, and your time-series values stay where they are. check lists the copy under Copied out of Postgres, and restore removes it again. If your 3.0 config.yaml no longer names that database, pass the 2.6 file with --from-config.

Secrets are now encrypted

2.6 stored some secrets in plain text. upgrade apply encrypts them, and the report lists one repair per secret without showing its value:

• the SAML service provider's private key (the admin screens now show it masked);
• the OIDC client secret and LDAP bind password of identity providers;
• the SMTP password;
• the keys that sign personal access tokens (PATs) and OAuth2 tokens;
• the access key ID of AWS Lambda, SNS and SQS connections, including in their version history;
• the context engine's API key to a Fleet Manager.

Personal access tokens and OAuth2 tokens keep working. The signing keys are encrypted, not replaced, so every token issued on 2.6 stays valid.

Where a module had no encryption key yet, apply creates one next to the other generated keys (on the single binary, in data/secrets/). The report lists each key file under Encryption keys. Keep these files with your data: without them, the secrets cannot be read.

The backup set still holds the old plain-text values. Protect it like the data itself, and delete it once 3.0 runs well.

If check or apply prints a SECURITY: warning about a publicly known key, rotate that module's key with admin-cli reencrypt <module> after the upgrade.

The shared uns_reader MQTT login is gone

2.6 generated a shared read-only MQTT login, uns_reader, and stored its password in plain text. 3.0 has no such login: MQTT subscribers that sign in with it stop connecting after the upgrade.

Before you upgrade, list the subscribers that use it and plan a login of their own for each: an API client with the read access it needs. You can register the API clients under API Clients on 2.6 already; they are kept by the upgrade. On 3.0, give each one the Data Stream Viewer role (Data.StreamViewer, which subscribes to topic streams), or subscribe access (topic:subscribe) shared on only the topics it needs. The Data Stream Viewer role is new in 3.0. Then switch each subscriber to its client's ID and secret, and to the topics' 3.0 paths (see UNS topic paths include the organization).

upgrade check notes the login, and upgrade apply removes its stored credential from the UNS settings and their saved copies, together with any access grants made to its subject, client:legacy-read-only.

An expired license no longer falls back to the trial

On 2.6, an instance whose license expired went back to the free trial, and every restart started a new trial. On 3.0, the free trial ends for good the first time the instance is licensed: a valid license key is applied, or a Fleet Manager licenses it. When that license expires, an administrator removes it, or the instance is disconnected from the Fleet Manager with no license key of its own, the instance is expired until a valid license is applied. Restarting does not start a trial, and Extend 2 hours is refused.

While an instance is expired, pipelines do not run and licensed features are off. Nothing is deleted.

upgrade check does not report this one. Open System Management → License on 2.6 before you upgrade: if the page shows a free trial on an instance you once licensed, the license has expired, and you need a valid key for 3.0. An instance that was never licensed keeps the trial as before.

A read from a disconnected device now fails the run

On 2.6, a read group whose connection could not read (for example, a PLC that was offline) could complete with empty values, and the pipeline went on to publish nulls. On 3.0, that read fails the node, and the run shows the failure. If a pipeline should go on without the values, set the node's On Error setting to continue.

A script failure has its own error code

On 2.6, a JavaScript node or an expression that threw or did not compile reported UNKNOWN_ERROR, TRANSIENT_ERROR or PERMANENT_ERROR. Which of the three it reported depended on the words in the error message. On 3.0, it always reports SCRIPT_ERROR. A JavaScript node that runs past its timeout reports TIMEOUT.

If a pipeline compares an error code with one of the old codes, for example a condition on a pipeline-event trigger's errors[].errorCode, check that it still catches what you expect. upgrade check lists every pipeline and node that contains one of the old codes. The upgrade does not change them.

Access changes are reported per user

The upgrade keeps each person's access as it was, except where the report says otherwise. upgrade check names every user, group and API client whose access changes, and why. The main changes:

• Organization settings belong to Organization.Admin. Identity.Admin and Security.Admin no longer read or update the organization's settings.
• Roles that 2.6.5 failed to apply now apply. On the 2.6.5 single binary, after a restart, the Connect, Automate and Data roles, Compliance.Auditor and the Fleet roles granted nothing. On 3.0 their holders get what the role says. The report lists each holder as a gain.
• Operator roles become Editor roles (Connect, Automate, Data).
• Secret.Revealer and Logging.Reader assignments are revoked. The report names each holder and what the role granted.
• Upgrading from 2.6.0: the report also covers the changes between 2.6.0 and 2.6.5, and names the release and change behind each one. For example, Organization.Admin no longer manages users, groups, identity providers and roles (give those people Identity.Admin), Member no longer publishes to UNS topics, and Platform.Admin and Platform.Viewer grant nothing.

Resources created on 2.6.0 may have no owner

2.6.0 kept ownership in a way that later releases did not carry over. On 3.0, a pipeline, connection, dashboard or library panel created on 2.6.0 may have no owner. Its creator keeps what their roles grant, but not the owner's extra rights, such as sharing their own pipeline. upgrade check names each such resource and its 2.6.0 owner.

An organization admin gives it an owner. The Pipelines, Connections and Dashboards lists mark such a resource No owner, and its row menu offers Assign owner. Library panels have no page action: use POST /api/v1/authz/resources/library_panel/<id>/ownership. A platform administrator assigns the owner of the organization record.

Knowledge model, schemas and alerts are rebuilt

3.0 rebuilds the knowledge model, schemas and alerts. The 2.6 schema registry, schema bindings, asset instances, inline topic schemas, alert limits and live alert state are not carried over. upgrade check reports how many of each will be dropped.

Connector behaviours that change on purpose

upgrade check gives each affected function a note:

• RabbitMQ publish waits for the broker's confirmation. On 2.6, a message the broker did not accept was lost without an error. On 3.0 that publish fails and can be retried. To publish without confirmation as on 2.6, set publisherConfirms: false on the function.
• FTP/SFTP rename no longer replaces an existing file. On 3.0 a rename onto an existing file fails unless the function sets overwrite: true.

Connector settings that 2.6 stored but never applied are removed, and the report names each one. Everything else a connection or function did on 2.6 is kept.

Also in 3.0:

• Some connector node types have new names. Each connector node type is now named after the operation it runs, connected.<operation>. The designer and the API use the new names. The 26 node types that shipped in 2.6 under another name are renamed in your stored pipelines by upgrade apply. check lists each one as a repair, naming the pipeline, the node, and the old and new type. A pipeline version saved before the upgrade is renamed too when you revert to it. A pipeline sent to the API without schemaVersion is read as a 2.6 pipeline and renamed the same way; one sent with 3.0's schemaVersion must use the new names.
• Store-and-forward now covers writes it skipped on 2.6. Where a node's store-and-forward setting asks for it, it now also holds back S3, Azure Blob, OneLake, GCS, SMB and local-file writes, and write requests made through nodes that run several operations, such as a REST request that posts. On 2.6 these writes were silently not buffered.

The first start runs long database work

Some database changes in 3.0 run at the first start, before MaestroHub answers, and on a large store they take minutes. check and apply list each one under At first start: the store, the change, the table's estimated rows and the store's size, the expected time as a range, and the free disk space it needs next to what the disk has. Too little disk, or an estimate longer than the Helm charts' 60-minute startup window, is also a warning. The two you are most likely to see:

• The audit store gets eight indexes, so that every audit trail filter is fast. The store grows while they are built, and needs free space for that growth.
• The execution history gets its 3.0 columns and indexes, including the one that folds repeated failures into one row (see Other changes). 2.6 created this store without the database's version table. The upgrade still reads the table that is there, and reports the work with its row count. Minutes after the first start, the execution history's retention (modules.pipelineEngine.executionRepository.sqlite.retention, carried over from your 2.6 config, 24h by default) deletes every run older than it; when that deletes any, check and apply add a note under Findings with the number of runs, the oldest, and the retention that keeps them — set it before you start 3.0 if you want them.

Until this work finishes, MaestroHub answers nothing and its container reports unhealthy. Do not stop or restart it: a stop rolls the change back, and the next start begins it again. The log reports progress every 15 seconds. If an orchestrator probes the container, give its startup probe as long as the estimate.

Other changes

• Repeated failures are one history row. When a pipeline fails the same way several times within one minute, the execution history shows one row, Failed ×N, with the first failed run kept in full and the last error. Every run is still counted. A success, or a different error, starts a new row.
• Old names are deprecated aliases. The maestrohub/lite image and the maestrohub-lite command still work in 3.0, with a warning. Move to maestrohub/context-engine and context-engine when convenient.
• Maestro chat: the 2.6 chat module was never released, so there is nothing to migrate. The Maestro agent is coming soon: it is in development and testing and is not part of release 3.0.
• Webhooks without authentication: a webhook trigger with no authentication headers, and without "allow unauthenticated" set, answers 401 on 3.0 until you configure it. The report gives it a note.

Image and command names

• maestrohub/lite:<3.0 version> is the same image as maestrohub/context-engine:<3.0 version>. The old name keeps working, but it is deprecated.
• maestrohub/lite:latest stays on 2.6.5 on purpose. An install or auto-updater that pulls :latest never lands on 3.0 by accident. Moving to 3.0 is always a deliberate tag change plus upgrade apply.
• The maestrohub-lite command inside the image also still works, with a warning that the name is deprecated.

To move off the old names, use image: maestrohub/context-engine:<version>, and context-engine instead of maestrohub-lite in command:. Both old names will be removed in a later release.