Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
run
✓ import { run } from 'mastra'
Primarily a CLI tool, programmatic imports are less common but may expose a 'run' function for advanced use cases.
Demonstrates initializing an agent with @mastra/core and how to use the 'mastra' CLI to deploy it. Note: replace 'gpt-4o' with a valid model.
import { Agent } from '@mastra/core';
const agent = new Agent({ name: 'MyFirstAgent', model: 'gpt-4o' });
// To run a command via the CLI (most common usage):
// npx mastra deploy MyFirstAgent --env production
mastra --version
Debug
Known issues
gotchaThe `mastra` CLI has a peer dependency on `zod` and `@mastra/core`. Ensure these are installed and compatible with your project.fixnpm install zod@'^3.25.0 || ^4.0.0' @mastra/core@'>=1.1.0-0 <2.0.0-0'
affects: *
breakingWorkspace filesystem path resolution now aligns with standard filesystem semantics. Absolute paths like `/file.txt` are no longer treated as workspace-relative but resolve to actual file system locations.fixReview existing workspace configurations that use absolute paths. Adjust them to be relative to the workspace root or ensure they correctly point to external absolute paths.
affects: >=1.12.0
gotchaEnd-to-end RAG tracing and new RAG/Graph span types (e.g., `RAG_INGESTION`) are opt-in and require an `observabilityContext` to be explicitly configured.fixPass an `observabilityContext` to relevant Mastra operations to enable tracing for RAG and graph interactions.
affects: >=1.24.0 (@mastra/core)
gotchaWorkspace tool output is now token-limited and ANSI-stripped for model context. This might affect applications that relied on full, unstripped terminal output from sandbox commands.fixIf full or ANSI-formatted output is required for external processing, consider using direct system commands or adapting your parsing logic to the new token-limited and stripped format.
affects: >=1.9.0 (@mastra/core)
deprecatedThe peer dependency `@mastra/core` is constrained to versions `>=1.1.0-0 <2.0.0-0`. Major version 2 of `@mastra/core` will likely introduce breaking changes and require an update to the `mastra` CLI.fixMonitor for future releases of `mastra` CLI that declare compatibility with `@mastra/core` v2. Plan for an upgrade when `@mastra/core` v2 is released.
affects: *
Errors
Common errors & fixes
mastra: command not found
The `mastra` package's executable is not in your system's PATH, or the package was not installed globally/linked correctly.
fixIf installed locally, run `npx mastra <command>`. If you intended a global install, run `npm install -g mastra` and ensure your global `node_modules` bin directory is in your PATH.
Error: Peer dependency "@mastra/core" is not installed or incompatible. Expected ">=1.1.0-0 <2.0.0-0".
The `@mastra/core` package, a required peer dependency for `mastra`, is either missing or its installed version does not meet the compatibility requirements.
fixRun `npm install @mastra/core@'>=1.1.0-0 <2.0.0-0'` in your project to install a compatible version.
Error: Zod peer dependency not found. Please install zod@^3.25.0 || ^4.0.0.
The `zod` validation library, a peer dependency, is not installed or its version is outside the supported range.
fixRun `npm install zod@'^3.25.0 || ^4.0.0'` in your project.
Error: RAG tracing requires an 'observabilityContext'. Please configure one.
You are attempting to use RAG tracing features without providing the necessary `observabilityContext` for instrumentation.
fixEnsure you initialize and pass an `observabilityContext` to the relevant RAG ingestion or query operations where tracing is desired.
Error: Workspace path '/absolute/path/to/file.txt' is no longer treated as workspace-relative. Use relative paths or verify the absolute path's intent.
Your workspace configuration or a tool within the workspace is using an absolute path (`/absolute/path/to/file.txt`) which is no longer interpreted relative to the workspace root after a breaking change in `@mastra/core` v1.12.0.
fixUpdate your workspace configuration to use paths relative to the workspace root for internal files, or explicitly manage absolute paths if they refer to external locations.
Audit
Dependencies
No dependency data recorded yet.