mastra-ai/mastra · error · HTTPException

Skill name and reference path are required

Error message

Skill name and reference path are required

What it means

The skill-reference handler requires both `skillName` (and `referencePath`) query/path parameters. If either is missing or empty, it rejects the request with 400 before doing any lookup. This is an input-validation guard for the reference fetch endpoint.

Source

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

  },
});

export const WORKSPACE_GET_SKILL_REFERENCE_ROUTE = createRoute({
  method: 'GET',
  path: '/workspaces/:workspaceId/skills/:skillName/references/:referencePath',
  responseType: 'json',
  pathParamSchema: skillReferencePathParams,
  queryParamSchema: skillDisambiguationQuerySchema,
  responseSchema: skillReferenceResponseSchema,
  summary: 'Get skill reference content',
  description: 'Returns the content of a specific reference file from a skill',
  tags: ['Workspace', 'Skills'],
  handler: async ({ mastra, skillName, path: skillPath, referencePath, workspaceId, requestContext }) => {
    try {
      requireWorkspaceV1Support();

      if (!skillName || !referencePath) {
        throw new HTTPException(400, { message: 'Skill name and reference path are required' });
      }

      // Use the optional ?path= query param for disambiguation, otherwise fall back to name
      const identifier = skillPath ? decodeURIComponent(skillPath) : 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 });

      // Resolve skill to get its name for the response
      const skill = await skills.get(identifier);
      if (!skill) {
        throw new HTTPException(404, { message: `Skill "${identifier}" not found` });
      }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Include both skillName and referencePath in the request (path/query as documented in the route).
2. Check for undefined/empty variables before constructing the URL on the client side.
3. Match the exact parameter names the route expects (skillName, referencePath, optional path).

Example fix

// before
const url = `/workspaces/ws1/skills/${undefined}/references/${ref}`
// after
if (!skillName || !referencePath) throw new Error('skillName and referencePath required');
const url = `/workspaces/ws1/skills/${encodeURIComponent(skillName)}/references/${encodeURIComponent(referencePath)}`;

if (!skillName?.trim() || !referencePath?.trim()) {
  throw new Error('Both skillName and referencePath are required before calling the reference API');
}

function hasRequiredRefParams(p: { skillName?: string; referencePath?: string }): p is { skillName: string; referencePath: string } {
  return typeof p.skillName === 'string' && p.skillName.length > 0 && typeof p.referencePath === 'string' && p.referencePath.length > 0;
}

try {
  return await client.getSkillReference({ skillName, referencePath });
} catch (e) {
  if (isHttpException(e, 400)) throw new Error('Client bug: missing skillName/referencePath — check URL construction');
  throw e;
}

When it happens

Trigger: Calling the skill reference endpoint without `skillName` or without `referencePath` (empty string counts as missing due to the falsy check), e.g. GET .../skills//references/some-file.md.

Common situations: Client builds the URL dynamically and one segment is undefined/null; query param name mismatch (e.g. sending `skill` instead of `skillName`); empty referencePath after template interpolation.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Agent ID is required
• Invalid skill name "${name}". Names must start with alphanum
• Could not derive scorer definition ID from name. Please prov
• skillPath is missing SKILL.md: ${resolvedPath}
• Argument "${key}" is required

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