MastraはTypeScriptベースの先進的AIエージェント開発フレームワークで、AIモデル連携・ワークフロー管理・テレメトリー監視機能を統合的に提供します。しかし、Windows環境での実行時に以下の2つの主要なエラーが発生しています。
-
パス解決エラー
/Users/user/.volta/bin/npxというmacOS形式のパスがWindows環境で使用され実行ファイルが見つからない -
テレメトリー設定エラー
.mastra/output/telemetry-config.mjsからtelemetryオブジェクトが正しくエクスポートされていない
技術的原因の詳細分析
パス解決エラーの根本原因
MastraのMCP（Model Context Protocol）設定がOS依存のパス記述となっているため159。Voltaのインストールパスは以下のようにOSによって異なります。
| OS | デフォルトパス |
|---|---|
| Windows | %APPDATA%\Volta\bin\npx.cmd |
| macOS | $HOME/.volta/bin/npx |
| Linux | $HOME/.volta/bin/npx |
テレメトリーエラーの根本原因
OpenTelemetry設定ファイルのエクスポート形式がCommonJS形式になっており、ESモジュール形式でのインポートに失敗していることが原因61216。特にWindows環境ではファイルパスの大文字小文字区別が影響するケースがあります。
段階的な解決手順
ステップ1：MCP設定の修正
src/mastra/agents/mcpAgent.tsを以下のように修正：
typescript
import { MCPConfiguration } from "@mastra/mcp";
import * as path from 'path';
const getNpxPath = () => {
if (process.platform === 'win32') {
return path.join(process.env.APPDATA || '', 'Volta', 'bin', 'npx.cmd');
}
return path.join(process.env.HOME || '', '.volta', 'bin', 'npx');
};
const mcp = new MCPConfiguration({
servers: {
"github": {
command: getNpxPath(),
args: ["-y", "@modelcontextprotocol/server-brave-search"],
env: {
BRAVE_API_KEY: process.env.BRAVE_API_KEY,
PATH: `${process.env.PATH};${path.dirname(getNpxPath())}`
}
}
}
});
ステップ2：テレメトリー設定の修正
.mastra/output/telemetry-config.mjsを以下のように再生成：
// telemetry-config.mjs
import { NodeSDK, Resource } from '@opentelemetry/sdk-node';
import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
export const telemetry = {
serviceName: '',
enabled: true,
sampling: { type: 'always_on' },
export: { type: 'console' }
};
export function initTelemetry() {
const exporter = new ConsoleSpanExporter();
return new NodeSDK({
resource: new Resource({
'service.name': telemetry.serviceName
}),
traceExporter: exporter
});
}
ステップ3：設定ファイルの統合
mastra.config.tsにテレメトリー設定を追加：
typescript
import { defineConfig } from '@mastra/core';
export default defineConfig({
telemetry: {
serviceName: '',
enabled: true,
export: { type: 'console' },
sampling: { type: 'always_on' }
},
agents: {
retryConfig: {
attempts: 3,
delay: 1000
}
}
});
予防措置とベストプラクティス
クロスプラットフォーム開発ガイドライン
typescript
const verifyEnvVars = () => {
const requiredVars = ['BRAVE_API_KEY'];
requiredVars.forEach(varName => {
if (!process.env[varName]) {
throw new Error(`${varName} 環境変数が設定されていません`);
}
});
};