Sync protocol changes, affecting third-party mobile apps coming in the next release

[eliandoran]

Hello @StephenArg , @FliegendeWurst ,

A change landing in Trilium after v0.106.0 (TriliumNext/Trilium#10647, not merged yet) affects clients that sync with or read from a Trilium server. Below is what changes on the server, followed by what I think TriliumDroid and Trinote each need.

Target date of the v0.107.0 release containing the sync protocol change: Oct 25th, 2026.

What changes on the server

The in-app help (_help and everything under it) is no longer stored in the database. The server builds it in memory at startup from files that ship with the application. It is never persisted and never synced.

Existing databases drop the stored copy in migration 242:

DELETE FROM entity_changes WHERE entityName = 'branches' AND entityId IN
    (SELECT branchId FROM branches WHERE noteId LIKE '\_help%' ESCAPE '\' OR parentNoteId LIKE '\_help%' ESCAPE '\');
DELETE FROM entity_changes WHERE entityName = 'attributes' AND entityId IN
    (SELECT attributeId FROM attributes WHERE noteId LIKE '\_help%' ESCAPE '\');
DELETE FROM entity_changes WHERE entityName = 'revisions' AND entityId IN
    (SELECT revisionId FROM revisions WHERE noteId LIKE '\_help%' ESCAPE '\');
DELETE FROM entity_changes WHERE entityName = 'attachments' AND entityId IN
    (SELECT attachmentId FROM attachments WHERE ownerId LIKE '\_help%' ESCAPE '\');
DELETE FROM entity_changes WHERE entityId LIKE '\_help%' ESCAPE '\';
DELETE FROM branches WHERE noteId LIKE '\_help%' ESCAPE '\' OR parentNoteId LIKE '\_help%' ESCAPE '\';
DELETE FROM attributes WHERE noteId LIKE '\_help%' ESCAPE '\';
DELETE FROM revisions WHERE noteId LIKE '\_help%' ESCAPE '\';
DELETE FROM attachments WHERE ownerId LIKE '\_help%' ESCAPE '\';
DELETE FROM notes WHERE noteId LIKE '\_help%' ESCAPE '\';

The migration deletes these rows directly and records no deletions. A client is never told through sync that the help notes are gone, and from then on it never receives them at all.

Other changes in this release:

• Versions: the sync protocol version goes to 41 and the database version to 242. Migration 241 deletes the web clipper's bx bx-globe icon labels, and those deletions sync normally. No release ships sync version 40.
• Help through the internal API: the virtual help notes are still served by /api/tree/load and the note blob routes like any other note.
  • Images in help pages use URLs relative to the server root: assets/<version>/help/User%20Guide/….
  • Help pages link to each other with href="#root/_help_…" note links.
• Read-only help: help notes were already read-only through an inheritable #readOnly label on _help. The server now also refuses to save their content, to clone or move them, or to create a note under one.
• Rest of the hidden subtree: _hidden, _options…, launchers and templates are still persisted and synced as before.

TriliumDroid (@FliegendeWurst)

1. Accept the new versions. Add 41 to SUPPORTED_SYNC_VERSIONS, add 241 and 242 to SUPPORTED_DATABASE_VERSIONS, and raise DATABASE_VERSION. Until then, syncStart reports "mismatched sync / database version".
2. Mirror migration 242 in CacheDbHelper.onUpgrade, the same way you mirrored 237. Otherwise an existing install keeps its stale copy of the help notes forever. Migration 241 needs no mirror.
3. Find another source for the Help menu. action_help opens _help from the local database, and sync no longer delivers it. A fresh install never gets one, and the menu then does nothing (Notes.getNote(help) ?: return@launch). Some options:
   • Open the online User Guide at https://docs.triliumnotes.org/.
   • Bundle a copy of the guide in the app.
   • Read it from the server's internal API. We have not checked whether the session from the sync login is enough to call those routes.

Trinote (@StephenArg)

As far as we can tell, nothing needs to change:

1. Versions. Trinote uses the web session, not /api/login/sync, so the sync version check does not apply to it. The only effect is the "newer than tested" notice in Settings. Once you have tested, raise testedMaxSyncVersion to 41 and testedMaxDbVersion to 242.
2. Help notes. Trinote leaves _hidden out of both its tree and its offline cache walk, and shows no help. The help notes that /api/sync/changed used to deliver are rem

The PR is still open, so details can change before release. We'll update this post if they do. Questions are welcome here.

[StephenArg]

@eliandoran Thanks for the heads up! I’ll try to account for this in the next update. I’m not sure I want to auto delete cached help notes on the phone. Aside from that I don’t think there’s much to change for me.

[eliandoran]

@eliandoran Thanks for the heads up! I’ll try to account for this in the next update. I’m not sure I want to auto delete cached help notes on the phone. Aside from that I don’t think there’s much to change for me.

Up to you, however it's important not to push them back in to other sync participants.

[eliandoran]

@FliegendeWurst , in addition #12144 now requires TOTP for sync (when enabled):

What changes: when TOTP is enabled on the server, GET /api/setup/sync-seed now requires the second factor, not just the password (#12144, fixing #8209 and #8272). Until now the seed — and with it the document secret — could be fetched with the password alone, which bypassed 2FA.

Who is affected: only a TriliumDroid instance that has no stored sync context yet (first setup, or after the database is reset) connecting to a server with TOTP enabled. Already configured instances keep syncing as before, since /api/login/sync is unchanged, and servers without TOTP behave exactly as today.

What the server expects:

• The code is sent in a trilium-totp header alongside trilium-cred. It accepts a TOTP code or a recovery code (a recovery code is used up).
• Responses on a server with TOTP enabled, all 401 with a text/plain body:
  • no trilium-totp header: TOTP token is required (returned before the password is checked)
  • wrong code: Incorrect TOTP token
  • wrong password: Incorrect password (unchanged)
• Older servers ignore the header, so always sending it when the user filled in a code is safe.

In practice this means an optional "One-time password or recovery code" field on the setup screen, and one header on the seed request in ConnectionUtil.fetch(). Note that with TOTP enabled, a missing code is reported before a wrong password, so the resp == "Incorrect password" check won't trigger until a code is sent.