mastra-ai/mastra · error · HTTPException

No workspace with skills configured

Error message

No workspace with skills configured

What it means

The get-skill-details route (GET /workspaces/:workspaceId/skills/:skillName) throws this 404 when the resolved workspace has no skills capability — getSkillsById(mastra, workspaceId) returns undefined because the workspace is not configured with skills (or no workspace exists). Skill lookup requires a workspace with a skills provider.

Source

Thrown at packages/server/src/server/handlers/workspace.ts:965

  queryParamSchema: skillDisambiguationQuerySchema,
  responseSchema: getSkillResponseSchema,
  summary: 'Get skill details',
  description: 'Returns the full details of a specific skill including instructions and file lists',
  tags: ['Workspace', 'Skills'],
  handler: async ({ mastra, skillName, path, workspaceId, requestContext }) => {
    try {
      requireWorkspaceV1Support();

      if (!skillName) {
        throw new HTTPException(400, { message: 'Skill name is required' });
      }

      // Use the optional ?path= query param for disambiguation, otherwise fall back to name
      const identifier = path ? decodeURIComponent(path) : skillName;

      const skills = await getSkillsById(mastra, workspaceId);
      if (!skills) {
        throw new HTTPException(404, { message: 'No workspace with skills configured' });
      }

      // Refresh skills with request context (handles dynamic skill resolvers)
      await skills.maybeRefresh({ requestContext });

      const skill = await skills.get(identifier);
      if (!skill) {
        throw new HTTPException(404, { message: `Skill "${identifier}" not found` });
      }

      return {
        name: skill.name,
        description: skill.description,
        license: skill.license,
        compatibility: skill.compatibility,
        metadata: skill.metadata,
        path: skill.path,
        instructions: skill.instructions,

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Configure skills on the target workspace (skills glob/directory or resolver) in the Mastra config.
  2. Confirm the workspaceId is correct and that GET /workspaces/:id/skills reports isSkillsConfigured: true.
  3. Deploy the same workspace/skills configuration used in the environment where it worked.
  4. If no workspace exists under that ID, fix the workspaceId first.

Example fix

// before
createWorkspace({ filesystem: fs }); // no skills configured
// after
createWorkspace({ filesystem: fs, skills: { globs: ['.agents/skills/*/SKILL.md'] } });
Defensive patterns

Strategy: fallback

Validate before calling

// Probe whether skills are configured for this workspace
const probe = await fetch(`/api/workspaces/${wsId}/skills`).then(r => r.json());
if (!probe.isSkillsConfigured) {
  throw new Error(`Workspace ${wsId} has no skills configured`);
}

Type guard

function skillsConfigured(p: { isSkillsConfigured?: boolean }): p is { isSkillsConfigured: true } {
  return p.isSkillsConfigured === true;
}

Try / catch

try {
  const skill = await getSkill(wsId, name);
} catch (e) {
  if (isHTTPException(e, 404) && e.message === 'No workspace with skills configured') {
    // degrade: hide skills UI or prompt admin to configure skills
  } else throw e;
}

Prevention

When it happens

Trigger: Calling GET /workspaces/:id/skills/:skillName against a workspace without skills configured; a workspaceId that has no workspace at all; server deployment lacking skills config (e.g. no skills glob/directory set).

Common situations: Environment drift: skills configured locally but not in the deployed Mastra instance; wrong workspaceId; Mastra version where workspace skills support is absent/disabled; calling skill routes on a filesystem-only workspace.

Related errors

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