mastra-ai/mastra · error · Error

Device credentials not found.

Error message

Device credentials not found.

What it means

updateCourseStateOnServer syncs course progress to mastra.ai and requires device credentials obtained via getDeviceCredentials(). If those credentials are missing (null), it throws 'Device credentials not found.' — the device has not been registered, so there is no device ID/key to authenticate the sync.

Source

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

          }
        });
      });
      req.on('error', error => {
        reject(error);
      });
      req.write(data);
      req.end();
    } catch (err) {
      reject(err);
    }
  });
}

// Create a function to update course state on the server
async function updateCourseStateOnServer(deviceId: string, state: CourseState): Promise<void> {
  const creds = await getDeviceCredentials();
  if (!creds) {
    throw new Error('Device credentials not found.');
  }

  const response = await fetch('https://mastra.ai/api/course/update', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-mastra-course-key': creds.key,
    },
    body: JSON.stringify({
      id: creds.deviceId,
      state: state,
    }),
  });

  if (!response.ok) {
    throw new Error(`Course state update failed with status ${response.status}: ${response.statusText}`);
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register the device / complete the course registration flow so getDeviceCredentials() returns credentials.
2. Verify the credentials file in ~/.cache/mastra (course state dir) exists and is readable.
3. If registration is not desired, avoid calling the state-saving course tools and use read-only course tools instead.

const creds = await getDeviceCredentials();
if (!creds) {
  // register the device before attempting any course state sync
  await registerDevice();
}
await saveCourseState(state, creds?.deviceId ?? null);

function hasDeviceCredentials(c: unknown): c is { deviceId: string } {
  return typeof c === 'object' && c !== null && typeof (c as { deviceId?: unknown }).deviceId === 'string' && (c as { deviceId: string }).deviceId.length > 0;
}

try {
  await saveCourseState(state, deviceId);
} catch (e) {
  if (e instanceof Error && e.message === 'Device credentials not found.') {
    // trigger device registration flow
  } else throw e;
}

When it happens

Trigger: Calling saveCourseState (via startMastraCourse, startMastraCourseLesson, nextMastraCourseStep) when the local device credentials store is empty — the user never completed registration/device pairing.

Common situations: Fresh machines or CI containers with no ~/.cache/mastra credentials; credentials file deleted; running the course tools before any registration step.

Related errors

• Invalid email or password
• Authentication failed / server-provided message
• Kimi For Coding credentials have an invalid device ID. Pleas
• No credentials
• Not logged in

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