# Set your Sage version compatibility

> Declare the oldest Sage release your app needs and the newest release you have tested.

The version fields in a Sage manifest answer different questions. Your app version identifies your release, the manifest version identifies the file format, and the Sage version range tells Sage whether the app is compatible with the version the user is running.

## Do not mix up the version fields

`version` identifies your app release. It is required app metadata, but it does not decide whether Sage sees an update. Sage compares the finalized manifest and its hash, so any finalized manifest change can produce an update without changing `version`.

`manifestVersion` identifies the Sage manifest file format. It is not your app version or the Sage release you support. It currently defaults to `0`, so a version 0 manifest can omit it.

`sageVersion.min` and `sageVersion.testedMax` describe compatibility with Sage itself. `min` is the hard lower boundary; `testedMax` is an optional upper testing boundary.

## Declare the compatibility range

Set `sageVersion.min` to the oldest Sage release that provides every API, capability, and behavior your app requires. Set `sageVersion.testedMax` to the newest Sage release on which you have actually tested the app.

Both values must be complete semantic versions such as `0.13.0`. When `testedMax` is present, it must be greater than or equal to `min`.

**Relevant sage-manifest.json fields**

```json
{
  "version": "1.4.0",
  "sageVersion": {
    "min": "0.13.0",
    "testedMax": "0.14.0"
  }
}
```

## Know what Sage enforces

If the user runs a Sage version below `min`, Sage blocks installing, updating to, or launching that app version. A blocked update leaves the currently installed app unchanged.

The range is inclusive. With `min` set to `0.13.0` and `testedMax` set to `0.14.0`, both boundary releases are compatible. A Sage release newer than `testedMax` produces a compatibility warning and requires review instead of being applied automatically, but the user can still install, update, and launch the app.

If `testedMax` is omitted, Sage applies no upper testing warning. An invalid semantic version, or a `testedMax` lower than `min`, makes the compatibility requirement invalid.

- Below `min`: blocked
- From `min` through `testedMax`: compatible
- Above `testedMax`: allowed with a warning

## Choose boundaries from real requirements

Raise `min` only when a release starts depending on something older Sage versions do not provide. A rebuild, content change, or ordinary app release is not by itself a reason to raise it.

Advance `testedMax` after testing against a newer Sage release. Keeping it honest gives users a useful warning when they are ahead of the versions you have verified; omitting it means future Sage releases will be treated as compatible without that warning.

## Test the boundaries before publishing

Test installation and launch on the exact `min` release and on the newest release you claim in `testedMax`. For an update, confirm that a compatible manifest applies normally and that an update requiring newer Sage does not replace the working installed version.

When practical, also check one release below `min` and one above `testedMax`. The first should be blocked with an upgrade requirement; the second should show a warning while still allowing the user to continue.

## Builder's note

Bridge APIs and client behavior can evolve. Verify implementation details against the Sage version you support, then test in both Sage and a normal browser.

---

Human-readable page: https://fancybudgie.com/sage/guides/sage-version-compatibility

Guide index: [llms.txt](https://fancybudgie.com/llms.txt)