mastra-ai/mastra · error · WorkspaceSkillInvocationError

skill_invocation_failed

skill_invocation_failed

Error message

Skill invocation failed (${response.status}).

What it means

Fallback thrown by requestWorkspaceSkill for any non-OK HTTP status from the skill endpoint. The client first tries to read { error, message } from the JSON body; if absent (or the body is HTML from an intermediary), it uses 'Skill invocation failed (<status>).' with code skill_invocation_failed and passes the real status code through.

Source

Thrown at mastracode/factory-ui/src/ui/domains/chat/services/agentControllerClient.ts:127

        502,
        'invalid_response',
      );
    }
    if (typeof result.skill === 'string' && typeof result.message === 'string') {
      return { skill: result.skill, message: result.message };
    }
    throw new WorkspaceSkillInvocationError('Skill invocation returned an invalid response.', 502, 'invalid_response');
  }

  let error: { error?: unknown; message?: unknown } = {};
  try {
    error = (await response.json()) as typeof error;
  } catch {
    // Preserve a useful status-based fallback when an intermediary returns HTML.
  }
  const code = typeof error.error === 'string' ? error.error : 'skill_invocation_failed';
  const message = typeof error.message === 'string' ? error.message : `Skill invocation failed (${response.status}).`;
  throw new WorkspaceSkillInvocationError(message, response.status, code);
}

export function prepareWorkspaceSkill(args: InvokeWorkspaceSkillArgs): Promise<{ skill: string; message: string }> {
  return requestWorkspaceSkill('prepare', args);
}

export function invokeWorkspaceSkill(args: InvokeWorkspaceSkillArgs): Promise<{ skill: string; message: string }> {
  return requestWorkspaceSkill('invoke', args);
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Check the response status in the network tab — the WorkspaceSkillInvocationError carries it as status/code.
2. For 401/403, re-authenticate the user session before invoking skills.
3. For 5xx, inspect server logs for the skill handler exception and fix or retry.
4. If the body was HTML, find the intermediary (proxy/LB) masking the real error and fix its configuration.

Example fix

// before (client)
const res = await fetch(url, { method: 'POST', body });
// after (client)
const res = await fetch(url, { method: 'POST', body });
if (res.status === 401) await refreshSession(); // then retry once
const result = await prepareWorkspaceSkill(args);

function isWorkspaceSkillError(e: unknown): e is WorkspaceSkillInvocationError {
  return e instanceof WorkspaceSkillInvocationError;
}

try {
  const result = await invokeWorkspaceSkill(args);
} catch (e) {
  if (e instanceof WorkspaceSkillInvocationError) {
    if (e.status === 401 || e.status === 403) redirectToLogin();
    else if (e.status >= 500) scheduleRetryWithBackoff();
    else showToast(e.message); // uses server message when present
  }
}

When it happens

Trigger: Skill endpoint returns 4xx/5xx — 401/403 auth failure, 404 route missing, 500 server error during skill execution, or a gateway 502/504 whose body isn't the expected JSON error envelope.

Common situations: Expired session cookie hitting a protected route; skill handler throwing server-side; load balancer returning an HTML error page; API route not deployed (404).

Related errors

• HTTP_ERROR
• Registration failed with status ${response.status}: ${respon
• Token exchange failed: ${error}
• Google Directory groups.list failed (${response.status}): ${
• Slack OAuth HTTP error: ${tokenResponse.status} ${tokenRespo

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