mastra-ai/mastra · error · Error

Failed to read step "${stepName}" in lesson "${lessonName}":

Error message

Failed to read step "${stepName}" in lesson "${lessonName}": ${error}

What it means

The step file was found, but fs.readFile failed when reading it from disk. The library wraps the underlying Node error (permissions, file removed between listing and read, encoding issues) in this message.

Source

Thrown at packages/mcp-docs-server/src/tools/course.ts:208

    throw new Error(`Lesson "${lessonName}" not found.`);
  }

  // Find the step file that matches the name
  const lessonPath = path.join(courseDir, lessonDir);
  const files = await fs.readdir(lessonPath);
  const stepFile = files.find(f => f.endsWith('.md') && f.replace(/^\d+-/, '').replace('.md', '') === stepName);

  if (!stepFile) {
    throw new Error(`Step "${stepName}" not found in lesson "${lessonName}".`);
  }

  const filePath = path.join(courseDir, lessonDir, stepFile);

  try {
    const content = await fs.readFile(filePath, 'utf-8');
    return wrapContentInPrompt(content);
  } catch (error) {
    throw new Error(`Failed to read step "${stepName}" in lesson "${lessonName}": ${error}`);
  }
}

// Create a function to update course state on the local server
export function updateCourseStateOnServerLocally(deviceId: string, state: CourseState): Promise<void> {
  return new Promise(async (resolve, reject) => {
    try {
      const creds = await getDeviceCredentials();
      if (!creds) {
        return reject(new Error('Device credentials not found.'));
      }
      const data = JSON.stringify({
        id: creds.deviceId,
        state: state,
      });
      const options = {
        hostname: 'localhost',
        port: 3000,

View on GitHub (pinned to 75dd419e61)

Solutions

Reinstall or repair the @mastra/mcp-docs-server package so course markdown files exist and are readable.
Check filesystem permissions on the course content directory and files (chmod/chown).
Retry the request if it was a transient race with a content update.

Defensive patterns

Strategy: retry

Validate before calling

import { accessSync, constants } from 'node:fs';
accessSync(filePath, constants.R_OK); // throws early if the file is not readable

Try / catch

try {
  const content = await stepContent({ lessonName, stepName });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Failed to read step')) {
    // check permissions / reinstall course content, optionally retry once
  } else throw e;
}

Prevention

Verify package integrity after installing/updating the docs server.
Run with a user that can read the package's course content files.
Retry once on transient EBUSY/ESTALE-style read failures.

When it happens

Trigger: fs.readFile(filePath, 'utf-8') rejects: file deleted/moved after readdir (race with course content update), insufficient read permissions, or I/O errors on the course directory.

Common situations: Partial/corrupted installation of the mcp-docs-server package where the course markdown files are missing or unreadable; running as a user without access to the package's files; course content changed mid-request.

Related errors

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