> ## Documentation Index
> Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading to momentic v3

> What changed in momentic 3.0 and how to move your web project from a 2.x release.

momentic 3.0 drops Node.js 20, retires the legacy `v1` AI agents, and removes a
few config options that are now handled automatically. This guide covers the
breaking changes and how to upgrade.

<Info>
  This guide is for the web CLI (`momentic`). Mobile (`momentic-mobile`) has its
  own [v1 upgrade guide](/get-started/upgrade-to-mobile-v1). If your repo has
  both, upgrade each separately.
</Info>

## 1. Use Node.js 22

momentic 3.0 requires **Node.js 22 or newer** - Node.js 20 has reached end of
life and is no longer supported. Check your version and upgrade if needed:

```bash theme={null}
node --version   # must be v22 or newer
```

Update the Node version in your CI images and any `.nvmrc` / `engines` field
before upgrading.

## 2. Run the upgrade

From your web project root:

```bash theme={null}
npx momentic@latest upgrade
```

This installs the latest CLI and applies the current recommended project
defaults. Pass `--dry-run` first to preview what would change without writing
anything.

## 3. Reinstall your browsers

momentic 3.0 bundles **Playwright 1.60.0**, which pins newer browser builds than
earlier releases. `momentic upgrade` does not download these for you, and your
existing browser binaries were installed for the old Playwright version, so
reinstall them after upgrading to avoid launch errors:

```bash theme={null}
npx momentic install-browsers chromium
```

Pass whichever browsers your tests use (`chromium`, `chrome`, or
`chrome-for-testing`), or `--all` to install every supported browser. See
[`momentic install-browsers`](/cli-reference/momentic/commands/install-browsers)
for details.

## 4. Breaking changes

Each of these requires an edit if your project uses the affected feature:

* **Legacy `v1` AI agents removed.** The `v1` locator, assertion, visual
  assertion, and text extraction agents have been retired. A run that pins one
  of these in `ai.agentConfig` in `momentic.config.yaml` now errors - switch
  those entries to a current version (see
  [AI configuration](/configuration/ai)).
* **`browser.bustCacheOnBoundingBoxChange` removed.** The element cache is now
  invalidated automatically when an element's bounding box changes, so the
  setting is no longer needed. Remove it from `momentic.config.yaml`.
* **`--record-video` flag removed.** Use `--video` instead (`--video true` to
  keep every recording, `--video false` to disable). Recording now defaults to
  `on-fail`: a video is captured for every run but kept only when the test
  fails.
* **AI Action steps default to the V3 agent.** The older V2 agent is marked
  "Legacy" and can no longer be selected for new AI Action steps in the editor.
  Existing V2 steps continue to run unchanged.

## 5. New-project defaults

These apply to projects created with `momentic init` and do not change existing
projects, but are worth knowing:

* Hybrid selectors are enabled by default
  (`browser.hybridSelectorMode: prefer`).
* New projects set `browser.disableSecondaryCacheResolution: true`.
* New projects pin each AI agent to the latest exact sub-version so defaults
  stay fixed when a newer revision ships.

Set any of these explicitly in `momentic.config.yaml` to override the default.

## Related

* [Simplified format](/get-started/migrate-to-simplified-format)
* [`momentic upgrade`](/cli-reference/momentic/commands/upgrade)
* [`momentic run`](/cli-reference/momentic/commands/run)
* [Browser configuration](/configuration/browser)
* [AI configuration](/configuration/ai)