Target component
Overview
The oxide CLI built from main or a given tagged release may fail when communicating with a rack running an older Omicron release. For example:
dev-machine $ oxide disk import --project example --path /path/to/disk --disk example_disk --description example --snapshot example_snapshot --image example_image --image-description testing --image-os debian --image-version 13.4.0
Which gives the output:
creating the disk failed: Error Response: status: 400 Bad Request; headers: {"content-type": "application/json", "x-request-id": "a3c0fe14-32fd-49d8-99fa-e77f3e4d9a97", "content-length": "150", "date": "Tue, 01 Apr 2026 00:00:00 GMT"}; value: Error { error_code: None, message: "unable to parse JSON body: missing field `disk_source` at line 1 column 164", request_id: "a3c0fe14-32fd-49d8-99fa-e77f3e4d9a97" }
Checking oxide version, we see:
dev-machine $ oxide version
Oxide CLI 0.15.0+2026021301.0.0
Built from commit: 68f182d88832582b765f31e70ea17de97f70c4cd
Oxide API: 2026021301.0.0
The cause being a schema change where disk_source was renamed to disk_backend starting in CLI version 15, with racks on older releases still expecting the original field name. Downgrading the CLI to the previous tag (v14) resolves the issue.
Note: I've linked changes to test files that illustrate this change inline above as an example as they are public, but can link to the internal PR change if need be.
Desired behavior:
When the CLI detects an incompatibility with the rack's API version, it should surface a clear error message rather than failing opaquely. This could take the form:
Version mismatch
The CLI version you are using requires a newer API schema.
- Rack API version: <version>
- Compatible CLI version: <version>
Implementation details
I think that this could be done by adding a check that could be called by the run function in cmd_version.rs.
Rather than checking for complete validity between versions, an inexpensive option could be to check the distance between the API version that the CLI expects, which I think could be fetched at any time via target_release object in the system update status endpoint.
Anything else you would like to add?
No response
Target component
Overview
The
oxideCLI built frommainor a given tagged release may fail when communicating with a rack running an older Omicron release. For example:Which gives the output:
Checking
oxide version, we see:The cause being a schema change where
disk_sourcewas renamed todisk_backendstarting in CLI version 15, with racks on older releases still expecting the original field name. Downgrading the CLI to the previous tag (v14) resolves the issue.Note: I've linked changes to test files that illustrate this change inline above as an example as they are public, but can link to the internal PR change if need be.
Desired behavior:
When the CLI detects an incompatibility with the rack's API version, it should surface a clear error message rather than failing opaquely. This could take the form:
Implementation details
I think that this could be done by adding a check that could be called by the run function in cmd_version.rs.
Rather than checking for complete validity between versions, an inexpensive option could be to check the distance between the API version that the CLI expects, which I think could be fetched at any time via
target_releaseobject in the system update status endpoint.Anything else you would like to add?
No response