mastra-ai/mastra · error

No exports are available from the top-level "@mastra/server"

Error message

No exports are available from the top-level "@mastra/server" package.

Use specific subpath imports instead, e.g. "@mastra/server/handlers" or "@mastra/server/handlers/tools".

What it means

The @mastra/server package intentionally exports nothing from its root entry point. Importing it at the top level executes this module, which immediately throws, and the error explains that consumers must use documented subpath exports such as '@mastra/server/handlers' or '@mastra/server/handlers/tools'. This guards the package's public API surface so internal modules are only reachable through stable subpaths.

Source

Thrown at packages/server/src/index.ts:1

throw new Error(`No exports are available from the top-level "@mastra/server" package.

Use specific subpath imports instead, e.g. "@mastra/server/handlers" or "@mastra/server/handlers/tools".`);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Change the import to the specific subpath you need, e.g. '@mastra/server/handlers' or '@mastra/server/handlers/tools'.
2. Check the package.json 'exports' field of @mastra/server for the full list of allowed subpaths.
3. Fix IDE auto-imports by choosing the subpath entry or configuring import resolution to respect package exports.

Example fix

// before
import { createHandler } from '@mastra/server';
// after
import { createHandler } from '@mastra/server/handlers';

// lint rule / manual check
// Bad: import x from '@mastra/server'
// Verify imports against package.json exports:
// node -e "console.log(Object.keys(require('@mastra/server/package.json').exports))"

When it happens

Trigger: Any import like import ... from '@mastra/server' or require('@mastra/server') — e.g. an IDE auto-import defaulting to the package root, or copying an old import path.

Common situations: IDE auto-completion picking the package root instead of a subpath; migrating code written before subpath-only exports were enforced; docs/examples referencing the root import.

Related errors

• INVALID_TSCONFIG
• [mastra/auth-ee] ${configuredFeatures.join(' and ')} ${confi
• [mastra/auth-ee] Agent Builder is configured but the EE modu

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/761e6f50ed00bc12. Report an issue: GitHub.