​

Matrix migration

• the plugin stays @pllan/matrix
• the channel stays matrix
• your config stays under channels.matrix
• cached credentials stay under ~/.pllan/credentials/matrix/
• runtime state stays under ~/.pllan/matrix/

​

What the migration does automatically

• source installs run pllan doctor --fix during the update flow, then restart the gateway by default
• package-manager installs update the package, run a non-interactive doctor pass, then rely on the default gateway restart so startup can finish Matrix migration
• if you use pllan update --no-restart, startup-backed Matrix migration is deferred until you later run pllan doctor --fix and restart the gateway

• creating or reusing a pre-migration snapshot under ~/Backups/pllan-migrations/
• reusing your cached Matrix credentials
• keeping the same account selection and channels.matrix config
• moving the oldest flat Matrix sync store into the current account-scoped location
• moving the oldest flat Matrix crypto store into the current account-scoped location when the target account can be resolved safely
• extracting a previously saved Matrix room-key backup decryption key from the old rust crypto store, when that key exists locally
• reusing the most complete existing token-hash storage root for the same Matrix account, homeserver, and user when the access token changes later
• scanning sibling token-hash storage roots for pending encrypted-state restore metadata when the Matrix access token changed but the account/device identity stayed the same
• restoring backed-up room keys into the new crypto store on the next Matrix startup

• Pllan writes a marker file at ~/.pllan/matrix/migration-snapshot.json after a successful snapshot so later startup and repair passes can reuse the same archive.
• These automatic Matrix migration snapshots back up config + state only (includeWorkspace: false).
• If Matrix only has warning-only migration state, for example because userId or accessToken is still missing, Pllan does not create the snapshot yet because no Matrix mutation is actionable.
• If the snapshot step fails, Pllan skips Matrix migration for that run instead of mutating state without a recovery point.

• the oldest flat Matrix store (~/.pllan/matrix/bot-storage.json and ~/.pllan/matrix/crypto/) came from a single-store layout, so Pllan can only migrate it into one resolved Matrix account target
• already account-scoped legacy Matrix stores are detected and prepared per configured Matrix account

​

What the migration cannot do automatically

• local-only room keys that were never backed up
• encrypted state when the target Matrix account cannot be resolved yet because homeserver, userId, or accessToken are still unavailable
• automatic migration of one shared flat Matrix store when multiple Matrix accounts are configured but channels.matrix.defaultAccount is not set
• custom plugin path installs that are pinned to a repo path instead of the standard Matrix package
• a missing recovery key when the old store had backed-up keys but did not keep the decryption key locally

• custom Matrix plugin path installs are surfaced by both gateway startup and pllan doctor

​

Recommended upgrade flow

1. Update Pllan and the Matrix plugin normally. Prefer plain pllan update without --no-restart so startup can finish the Matrix migration immediately.
2. Run:
   Copy

   Ask AI

   pllan doctor --fix
   
   If Matrix has actionable migration work, doctor will create or reuse the pre-migration snapshot first and print the archive path.
3. Start or restart the gateway.
4. Check current verification and backup state:
   Copy

   Ask AI

   pllan matrix verify status
   pllan matrix verify backup status
   
5. If Pllan tells you a recovery key is needed, run:
   Copy

   Ask AI

   pllan matrix verify backup restore --recovery-key "<your-recovery-key>"
   
6. If this device is still unverified, run:
   Copy

   Ask AI

   pllan matrix verify device "<your-recovery-key>"
   
7. If you are intentionally abandoning unrecoverable old history and want a fresh backup baseline for future messages, run:
   Copy

   Ask AI

   pllan matrix verify backup reset --yes
   
8. If no server-side key backup exists yet, create one for future recoveries:
   Copy

   Ask AI

   pllan matrix verify bootstrap
   

​

How encrypted migration works

1. Startup or pllan doctor --fix creates or reuses the pre-migration snapshot if encrypted migration is actionable.
2. Startup or pllan doctor --fix inspects the old Matrix crypto store through the active Matrix plugin install.
3. If a backup decryption key is found, Pllan writes it into the new recovery-key flow and marks room-key restore as pending.
4. On the next Matrix startup, Pllan restores backed-up room keys into the new crypto store automatically.

​

Common messages and what they mean

​

Upgrade and detection messages

• Meaning: the old on-disk Matrix state was detected and migrated into the current layout.
• What to do: nothing unless the same output also includes warnings.

• Meaning: Pllan created a recovery archive before mutating Matrix state.
• What to do: keep the printed archive path until you confirm migration succeeded.

• Meaning: Pllan found an existing Matrix migration snapshot marker and reused that archive instead of creating a duplicate backup.
• What to do: keep the printed archive path until you confirm migration succeeded.

• Meaning: old Matrix state exists, but Pllan cannot map it to a current Matrix account because Matrix is not configured.
• What to do: configure channels.matrix, then rerun pllan doctor --fix or restart the gateway.

• Meaning: Pllan found old state, but it still cannot determine the exact current account/device root.
• What to do: start the gateway once with a working Matrix login, or rerun pllan doctor --fix after cached credentials exist.

• Meaning: Pllan found one shared flat Matrix store, but it refuses to guess which named Matrix account should receive it.
• What to do: set channels.matrix.defaultAccount to the intended account, then rerun pllan doctor --fix or restart the gateway.

• Meaning: the new account-scoped location already has a sync or crypto store, so Pllan did not overwrite it automatically.
• What to do: verify that the current account is the correct one before manually removing or moving the conflicting target.

• Meaning: Pllan tried to move old Matrix state but the filesystem operation failed.
• What to do: inspect filesystem permissions and disk state, then rerun pllan doctor --fix.

• Meaning: Pllan found an old encrypted Matrix store, but there is no current Matrix config to attach it to.
• What to do: configure channels.matrix, then rerun pllan doctor --fix or restart the gateway.

• Meaning: the encrypted store exists, but Pllan cannot safely decide which current account/device it belongs to.
• What to do: start the gateway once with a working Matrix login, or rerun pllan doctor --fix after cached credentials are available.

• Meaning: Pllan found one shared flat legacy crypto store, but it refuses to guess which named Matrix account should receive it.
• What to do: set channels.matrix.defaultAccount to the intended account, then rerun pllan doctor --fix or restart the gateway.

• Meaning: Pllan detected old Matrix state, but the migration is still blocked on missing identity or credential data.
• What to do: finish Matrix login or config setup, then rerun pllan doctor --fix or restart the gateway.

• Meaning: Pllan found old encrypted Matrix state, but it could not load the helper entrypoint from the Matrix plugin that normally inspects that store.
• What to do: reinstall or repair the Matrix plugin (pllan plugins install @pllan/matrix, or pllan plugins install ./extensions/matrix for a repo checkout), then rerun pllan doctor --fix or restart the gateway.

• Meaning: Pllan found a helper file path that escapes the plugin root or fails plugin boundary checks, so it refused to import it.
• What to do: reinstall the Matrix plugin from a trusted path, then rerun pllan doctor --fix or restart the gateway.

• Meaning: Pllan refused to mutate Matrix state because it could not create the recovery snapshot first.
• What to do: resolve the backup error, then rerun pllan doctor --fix or restart the gateway.

• Meaning: the Matrix client-side fallback found old flat storage, but the move failed. Pllan now aborts that fallback instead of silently starting with a fresh store.
• What to do: inspect filesystem permissions or conflicts, keep the old state intact, and retry after fixing the error.

• Meaning: Matrix is pinned to a path install, so mainline updates do not automatically replace it with the repo’s standard Matrix package.
• What to do: reinstall with pllan plugins install @pllan/matrix when you want to return to the default Matrix plugin.

​

Encrypted-state recovery messages

• Meaning: backed-up room keys were restored successfully into the new crypto store.
• What to do: usually nothing.

• Meaning: some old room keys existed only in the old local store and had never been uploaded to Matrix backup.
• What to do: expect some old encrypted history to remain unavailable unless you can recover those keys manually from another verified client.

• Meaning: backup exists, but Pllan could not recover the recovery key automatically.
• What to do: run pllan matrix verify backup restore --recovery-key "<your-recovery-key>".

• Meaning: Pllan found the old encrypted store, but it could not inspect it safely enough to prepare recovery.
• What to do: rerun pllan doctor --fix. If it repeats, keep the old state directory intact and recover using another verified Matrix client plus pllan matrix verify backup restore --recovery-key "<your-recovery-key>".

• Meaning: Pllan detected a backup key conflict and refused to overwrite the current recovery-key file automatically.
• What to do: verify which recovery key is correct before retrying any restore command.

• Meaning: this is the hard limit of the old storage format.
• What to do: backed-up keys can still be restored, but local-only encrypted history may remain unavailable.

• Meaning: the new plugin attempted restore but Matrix returned an error.
• What to do: run pllan matrix verify backup status, then retry with pllan matrix verify backup restore --recovery-key "<your-recovery-key>" if needed.

​

Manual recovery messages

• Meaning: Pllan knows you should have a backup key, but it is not active on this device.
• What to do: run pllan matrix verify backup restore, or pass --recovery-key if needed.

• Meaning: this device does not currently have the recovery key stored.
• What to do: verify the device with your recovery key first, then restore the backup.

• Meaning: the stored key does not match the active Matrix backup.
• What to do: rerun pllan matrix verify device "<your-recovery-key>" with the correct key.

• Meaning: the backup exists, but this device does not trust the cross-signing chain strongly enough yet.
• What to do: rerun pllan matrix verify device "<your-recovery-key>".

• Meaning: you tried a recovery step without supplying a recovery key when one was required.
• What to do: rerun the command with your recovery key.

• Meaning: the provided key could not be parsed or did not match the expected format.
• What to do: retry with the exact recovery key from your Matrix client or recovery-key file.

• Meaning: the key was applied, but the device still could not complete verification.
• What to do: confirm you used the correct key and that cross-signing is available on the account, then retry.

• Meaning: secret storage did not produce an active backup session on this device.
• What to do: verify the device first, then recheck with pllan matrix verify backup status.

• Meaning: this device cannot restore from secret storage until device verification is complete.
• What to do: run pllan matrix verify device "<your-recovery-key>" first.

​

Custom plugin install messages

• Meaning: your plugin install record points at a local path that is gone.
• What to do: reinstall with pllan plugins install @pllan/matrix, or if you are running from a repo checkout, pllan plugins install ./extensions/matrix.

​

If encrypted history still does not come back

pllan matrix verify status --verbose
pllan matrix verify backup status --verbose
pllan matrix verify backup restore --recovery-key "<your-recovery-key>" --verbose

​

If you want to start fresh for future messages

pllan matrix verify backup reset --yes
pllan matrix verify backup status --verbose
pllan matrix verify status

​

Related pages

• Matrix
• Doctor
• Migrating
• Plugins