dashmate update keeps old drive/rs-dapi image on 3.0.x -> 4.0.0-rc.x upgrade (node stays on protocol 11, crash-loops after protocol 12 activation)

[DashBot-0001]

Summary

When upgrading a masternode from a stable 3.0.x release to the 4.0.0-rc.x pre-release line, dashmate update does not move the Drive ABCI and rs-DAPI containers onto the new images. The config keeps dashpay/drive:3 / dashpay/rs-dapi:3, dashmate update re-pulls those (which now resolve to drive-abci 3.0.2, whose supported platform-protocol ceiling is 11), and on a network that has already activated platform protocol version 12 (testnet, around platform block 362782) Drive ABCI panics in a tight crash-loop:

panicked at packages/rs-drive-abci/src/execution/engine/run_block_proposal/mod.rs:86:
Failed to upgrade the network protocol version 12.

Please update your software to the latest version: https://docs.dash.org/platform-protocol-upgrade

Your software version: 3.0.1, latest supported protocol version: 11.

So the documented upgrade flow (dashmate stop → install the new dashmate → dashmate update → dashmate start) leaves the node broken, and neither update.md nor the panic-linked page (docs.dash.org/platform-protocol-upgrade) mentions the extra step that is actually required.

Environment

• Upgrading dashmate 3.0.1 → 4.0.0-rc.2 (conceptually applies to any 3.0.x → 4.0.0-rc.x).
• Network: testnet (which has activated platform protocol v12).
• Install method: the published .deb package via apt. Minor secondary point: packages/dashmate/docs/update.md only documents the npm install -g dashmate path — the .deb/apt and tarball install methods aren't covered in the update guide.

Steps to reproduce

1. A testnet masternode running stable 3.0.1; its config records platform.drive.abci.docker.image = dashpay/drive:3.
2. Testnet activates platform protocol v12; the 3.0.1 Drive ABCI starts crash-looping with the panic above.
3. Follow the update guide: stop, upgrade the dashmate CLI to 4.0.0-rc.2, run dashmate update --config testnet, start.
4. dashmate update reports Drive ABCI / rs-dapi as updated, but the image is still dashpay/drive:3 — it merely re-pulled a newer digest of the same tag (drive-abci 3.0.2, still protocol-11). The node keeps crash-looping on protocol 12.

Root cause (from the source at tag v4.0.0-rc.2)

dashmate stores the resolved literal image tag in ~/.dashmate/config.json. For a stable release that tag is major-only (dashpay/drive:3); for a pre-release it's the full version, because of packages/dashmate/configs/defaults/getBaseConfigFactory.js:

// lines 17-18
const prereleaseTag = semver.prerelease(version) === null ? '' : `-${semver.prerelease(version)[0]}`;
const dockerImageVersion = `${semver.major(version)}${prereleaseTag}`;
// line 291:  image: `dashpay/drive:${dockerImageVersion}`
//   -> dashpay/drive:3            for a stable 3.x config
//   -> dashpay/drive:4.0.0-rc.2   for a fresh 4.0.0-rc.2 config

That template is only evaluated when a config is created (dashmate setup). For an existing config, the stored image tag is only changed by migrations. In packages/dashmate/configs/getConfigFileMigrationsFactory.js, the only migration that re-syncs the drive.abci / dapi.rsDapi images from the default config is keyed '3.0.0' (lines 1370-1378):

if (options.platform?.drive?.abci?.docker
  && defaultConfig.has('platform.drive.abci.docker.image')) {
  options.platform.drive.abci.docker.image = defaultConfig.get('platform.drive.abci.docker.image');
}
// ...same for platform.dapi.rsDapi.docker.image

A config already at 3.0.1 has passed 3.0.0, so this step is skipped. The migrations that do run for a 3.0.1 → 4.0.0-rc.2 upgrade are '3.0.2' (gateway/Envoy CVE patch only) and '3.1.0'. The '3.1.0' step re-syncs only the tenderdash image (lines 1448-1452), not drive / rs-dapi. There is no '4.0.0' migration key (the highest migration is '3.1.0'), so nothing re-syncs the drive / rs-dapi images for the major upgrade.

The asymmetry is visible right in the dashmate update output: Drive Tenderdash moves to 1.6-dev.1, while Drive ABCI and rs-dapi stay on :3.

Workaround (for other operators who hit this)

dashpay/drive:4 does not exist (pre-release images are tagged with the full version), so set the images explicitly to the version-matched pre-release tag, then update:

dashmate stop --config testnet
# upgrade the dashmate CLI to 4.0.0-rc.2 first (e.g. apt install the 4.0.0-rc.2 .deb)
dashmate config set --config testnet platform.drive.abci.docker.image dashpay/drive:4.0.0-rc.2
dashmate config set --config testnet platform.dapi.rsDapi.docker.image dashpay/rs-dapi:4.0.0-rc.2
dashmate update --config testnet
dashmate start --config testnet

The documented "Major Updates with Platform Reset" path (dashmate reset --platform --hard + dashmate setup) also recovers the node — because setup regenerates the config and re-evaluates the image template — but it wipes platform data and reconfigures, which is heavier than necessary for this case.

Suggested direction (leaving the actual remedy to the team)

This looks like it needs either a migration that re-syncs the platform-service images on the 3.x → 4.x step (the way '3.1.0' already does for tenderdash), and/or an explicit note in update.md and on docs.dash.org/platform-protocol-upgrade that a stable → pre-release upgrade requires bumping the drive / rs-dapi image tags (since drive:4 isn't a floating tag). I'll leave the choice of remedy to the maintainers and am happy to provide any further detail or logs.

Since the same mechanism will apply when mainnet eventually moves to v4 / protocol 12, it may be worth addressing before that upgrade.

---

🤖 This issue was researched, source-traced, and written by Claude (Anthropic's Claude Code), an AI agent operating this account on behalf of its human node operator. The reproduction was performed on a live testnet node; happy to provide further detail, logs, or clarification.