mastra-ai/mastra · error

Need MOONSHOT_API_KEY

Error message

Need MOONSHOT_API_KEY

What it means

resolveLanguageModel for Moonshot (Anthropic-compatible endpoint) requires an API key and throws 'Need MOONSHOT_API_KEY' when none is found. It checks args.apiKey, then MOONSHOT_API_KEY, then the legacy typo MOONSHOT_AI_API_KEY.

Source

Thrown at mastracode/sdk/src/agents/mastracode-gateway.ts:490

      });
      return provider.chatModel(args.modelId) as unknown as GatewayLanguageModel;
    }

    if (args.providerId === 'github-copilot') {
      return githubCopilotProvider(args.modelId, {
        headers: args.headers,
        authStorage: this.#credentials,
      }) as unknown as GatewayLanguageModel;
    }

    if (args.providerId === 'moonshotai') {
      // Prefer the gateway-resolved key (stored credentials), then the canonical
      // registry env var. Keep the legacy typo name as a fallback for anyone who
      // set it because of the previous error message.
      const apiKey =
        args.apiKey?.trim() || process.env.MOONSHOT_API_KEY?.trim() || process.env.MOONSHOT_AI_API_KEY?.trim();
      if (!apiKey) {
        throw new Error('Need MOONSHOT_API_KEY');
      }
      return createAnthropic({
        apiKey,
        baseURL: 'https://api.moonshot.ai/anthropic/v1',
        name: 'moonshotai.anthropicv1',
        headers: args.headers,
      })(args.modelId) as unknown as GatewayLanguageModel;
    }

    if (args.providerId === 'anthropic') {
      return this.#resolveAnthropicModel(args);
    }

    if (args.providerId === 'openai') {
      const openaiModel = this.#resolveOpenAIModel(args);
      if (openaiModel) return openaiModel;
    }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set MOONSHOT_API_KEY in the environment with a valid Moonshot API key
2. Pass the key explicitly via args.apiKey when constructing/resolving the model
3. Ensure your .env file is actually loaded by the process
4. Rename legacy MOONSHOT_AI_API_KEY to MOONSHOT_API_KEY to standardize
5. Verify the key works: `curl https://api.moonshot.ai/...` with the key

Example fix

// before
const model = gatewayModel('moonshotai/kimi-k2'); // no key anywhere
// after
process.env.MOONSHOT_API_KEY = 'sk-...';
const model = gatewayModel('moonshotai/kimi-k2');

const key = process.env.MOONSHOT_API_KEY?.trim();
if (!key) throw new Error('Set MOONSHOT_API_KEY before resolving moonshot models');

const hasMoonshotKey = (): boolean =>
  Boolean(process.env.MOONSHOT_API_KEY?.trim() || process.env.MOONSHOT_AI_API_KEY?.trim());

try {
  const model = resolveModel('moonshotai/kimi-k2');
} catch (err) {
  if ((err as Error).message === 'Need MOONSHOT_API_KEY') {
    console.error('Set MOONSHOT_API_KEY in your environment or pass apiKey explicitly');
  } else throw err;
}

When it happens

Trigger: A Moonshot gateway model is resolved with `args.apiKey` empty/whitespace and neither MOONSHOT_API_KEY nor MOONSHOT_AI_API_KEY is set in the environment.

Common situations: Deploying without the env var configured, key set under a differently named variable, running in an environment where .env is not loaded, or relying on the old typo'd MOONSHOT_AI_API_KEY in a context where it was dropped.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• VoyageAI API key is required. Set VOYAGE_API_KEY environment
• VoyageAI API key is required. Set VOYAGE_API_KEY environment
• VoyageAI API key is required. Set VOYAGE_API_KEY environment
• VoyageAI API key is required. Set VOYAGE_API_KEY environment
• API key not found for provider mastra. Set MASTRA_GATEWAY_AP

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