# Upgrade to Mastra v1

> **Update to latest 0.x version:** Before upgrading to v1, make sure you've updated to the latest 0.x version of Mastra. Follow the [upgrade to latest 0.x guide](https://mastra.ai/guides/v0/migrations/upgrade-to-latest-0x) first, then return here to complete the v1 migration.

Mastra v1 was released in January 2026. We recommend starting any new projects with Mastra v1, or upgrading your existing project to continue receiving updates and support.

This guide provides a comprehensive overview of breaking changes when upgrading from Mastra 0.x to v1.0. The migration is organized by package and feature area to help you systematically update your codebase.

> **Need help?:** Need help with the migration? Join our [Discord community](https://discord.gg/BTYqqHKUrf) to ask questions.

## Migration strategy

### Update all Mastra packages to `latest` tag

Use your package manager to update your project's versions. Be sure to update **all** Mastra packages at the same time to ensure compatibility (all `@mastra/*` packages and `mastra`).

Here's how you update the most commonly used packages:

**npm**:

```bash
npm install @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest
```

**pnpm**:

```bash
pnpm add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest
```

**Yarn**:

```bash
yarn add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest
```

**Bun**:

```bash
bun add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest
```

Install any other Mastra package with the `@latest` tag and you'll get the latest v1 version available. Be sure to update all Mastra packages (especially if you're in a monorepo) to avoid version mismatches.

### Update Node.js version

Mastra v1 requires Node.js **22.13.0** or higher. Update your development and production environments accordingly.

### Go through migration checklist

Work through the [migration checklist](#migration-checklist) below to update your codebase. Each item links to a detailed guide for that specific change.

> **Codemods:** We prepared automated [codemods](https://github.com/mastra-ai/mastra/tree/main/packages/codemod) for you. If you want, you can run all v1 codemods at once:
>
> ```bash
> npx @mastra/codemod@latest v1
> ```

> **Database Migration Required:** If you're using PostgreSQL or LibSQL storage, you'll need to run a database migration. See the [Storage migration guide](https://mastra.ai/guides/migrations/upgrade-to-v1/storage) for details.

## Breaking changes by area

- **[Mastra Class](https://mastra.ai/guides/migrations/upgrade-to-v1/mastra)** - Import restructuring and property access changes.
- **[Agent Class](https://mastra.ai/guides/migrations/upgrade-to-v1/agent)** - Voice methods moved to namespace and streaming API updates.
- **[Tools](https://mastra.ai/guides/migrations/upgrade-to-v1/tools)** - CreateTool execute signature changed to separate input and context.
- **[Workflows](https://mastra.ai/guides/migrations/upgrade-to-v1/workflows)** - Function name changes and legacy features removed.
- **[Memory](https://mastra.ai/guides/migrations/upgrade-to-v1/memory)** - Configuration now requires explicit parameters and defaults changed.
- **[Storage](https://mastra.ai/guides/migrations/upgrade-to-v1/storage)** - Pagination standardized and methods renamed to list pattern.
- **[Vectors](https://mastra.ai/guides/migrations/upgrade-to-v1/vectors)** - Vector store methods renamed to list pattern.
- **[RAG](https://mastra.ai/guides/migrations/upgrade-to-v1/rag)** - Parameter naming updated for clarity.
- **[MCP](https://mastra.ai/guides/migrations/upgrade-to-v1/mcp)** - Tool context reorganized and deprecated client classes removed.
- **[Tracing](https://mastra.ai/guides/migrations/upgrade-to-v1/tracing)** - OTEL telemetry replaced with dedicated observability package and exporters.
- **[Evals & Scorers](https://mastra.ai/guides/migrations/upgrade-to-v1/evals)** - Scorers API consolidated with new naming conventions.
- **[CLI](https://mastra.ai/guides/migrations/upgrade-to-v1/cli)** - Commands and flags removed for simpler interface.
- **[Deployment](https://mastra.ai/guides/migrations/upgrade-to-v1/deployment)** - CloudflareDeployer configuration updated to use standard wrangler.json property names.
- **[Client SDKs](https://mastra.ai/guides/migrations/upgrade-to-v1/client)** - Types and utilities renamed for consistency.
- **[Voice Packages](https://mastra.ai/guides/migrations/upgrade-to-v1/voice)** - Packages renamed from speech to voice.

## Migration checklist

Work through this checklist in order, starting with high-impact changes that affect most applications.

> **Codemods:** We prepared automated [codemods](https://github.com/mastra-ai/mastra/tree/main/packages/codemod) for you. Throughout the migration guide you'll find instructions on how to use them for specific changes.
>
> If you want, you can run all v1 codemods at once:
>
> ```bash
> npx @mastra/codemod@latest v1
> ```

### High Impact Changes

- Update `createTool` tool signatures to `(inputData, context)` format - [Tools](https://mastra.ai/guides/migrations/upgrade-to-v1/tools)
- Restructure `@mastra/core` imports to use subpath imports - [Mastra Class](https://mastra.ai/guides/migrations/upgrade-to-v1/mastra)
- Update pagination from `offset/limit` to `page/perPage` - [Storage](https://mastra.ai/guides/migrations/upgrade-to-v1/storage)
- Install `@mastra/observability` and wrap configuration with `new Observability()` - [Tracing](https://mastra.ai/guides/migrations/upgrade-to-v1/tracing)
- Migrate from `telemetry:` to `observability:` configuration (if upgrading from 0.x OTEL) - [Tracing](https://mastra.ai/guides/migrations/upgrade-to-v1/tracing)

### Medium Impact Changes

- Rename `RuntimeContext` to `RequestContext` throughout codebase - [Agent Class](https://mastra.ai/guides/migrations/upgrade-to-v1/agent), [Tools](https://mastra.ai/guides/migrations/upgrade-to-v1/tools), [Workflows](https://mastra.ai/guides/migrations/upgrade-to-v1/workflows)
- Update storage methods from `get*` to `list*` pattern - [Storage](https://mastra.ai/guides/migrations/upgrade-to-v1/storage)
- Replace direct property access with getter methods - [Mastra Class](https://mastra.ai/guides/migrations/upgrade-to-v1/mastra), [Agent Class](https://mastra.ai/guides/migrations/upgrade-to-v1/agent)
- Update memory scope if relying on default `thread` scope - [Memory](https://mastra.ai/guides/migrations/upgrade-to-v1/memory)
- Update vector store calls to use named arguments - [Storage](https://mastra.ai/guides/migrations/upgrade-to-v1/storage)
- Remove `format` parameter from agent methods - [Agent Class](https://mastra.ai/guides/migrations/upgrade-to-v1/agent)
- Update voice methods to use `agent.voice` namespace - [Agent Class](https://mastra.ai/guides/migrations/upgrade-to-v1/agent)
- Rename configuration property `processors` to `spanOutputProcessors` (if using custom processors) - [Tracing](https://mastra.ai/guides/migrations/upgrade-to-v1/tracing)

### Low Impact Changes

- Rename `keepSeparator` to `separatorPosition` in chunk options - [RAG](https://mastra.ai/guides/migrations/upgrade-to-v1/rag)
- Rename `createRunAsync` to `createRun` - [Workflows](https://mastra.ai/guides/migrations/upgrade-to-v1/workflows)
- Update voice package names from `@mastra/speech-*` to `@mastra/voice-*` - [Voice Packages](https://mastra.ai/guides/migrations/upgrade-to-v1/voice)
- Update scorer methods: `runExperiment` → `runEvals`, `getScorerByName` → `getScorerById` - [Evals & Scorers](https://mastra.ai/guides/migrations/upgrade-to-v1/evals)
- Remove deprecated CLI flags - [CLI](https://mastra.ai/guides/migrations/upgrade-to-v1/cli)
- Update client SDK types from `Get*` to `List*` - [Client SDKs](https://mastra.ai/guides/migrations/upgrade-to-v1/client)
- Replace `runCount` with `retryCount` - [Workflows](https://mastra.ai/guides/migrations/upgrade-to-v1/workflows)
- Update custom exporter method `exportEvent` to `exportTracingEvent` (if using custom exporters) - [Tracing](https://mastra.ai/guides/migrations/upgrade-to-v1/tracing)