{"record":{"id":"1dac7e6f8abc9a7b","repo":"mastra-ai/mastra","slug":"skill-name-and-reference-path-are-required","errorCode":null,"errorMessage":"Skill name and reference path are required","messagePattern":"Skill name and reference path are required","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/workspace.ts","lineNumber":1056,"sourceCode":"  },\n});\n\nexport const WORKSPACE_GET_SKILL_REFERENCE_ROUTE = createRoute({\n  method: 'GET',\n  path: '/workspaces/:workspaceId/skills/:skillName/references/:referencePath',\n  responseType: 'json',\n  pathParamSchema: skillReferencePathParams,\n  queryParamSchema: skillDisambiguationQuerySchema,\n  responseSchema: skillReferenceResponseSchema,\n  summary: 'Get skill reference content',\n  description: 'Returns the content of a specific reference file from a skill',\n  tags: ['Workspace', 'Skills'],\n  handler: async ({ mastra, skillName, path: skillPath, referencePath, workspaceId, requestContext }) => {\n    try {\n      requireWorkspaceV1Support();\n\n      if (!skillName || !referencePath) {\n        throw new HTTPException(400, { message: 'Skill name and reference path are required' });\n      }\n\n      // Use the optional ?path= query param for disambiguation, otherwise fall back to name\n      const identifier = skillPath ? decodeURIComponent(skillPath) : skillName;\n\n      const skills = await getSkillsById(mastra, workspaceId);\n      if (!skills) {\n        throw new HTTPException(404, { message: 'No workspace with skills configured' });\n      }\n\n      // Refresh skills with request context (handles dynamic skill resolvers)\n      await skills.maybeRefresh({ requestContext });\n\n      // Resolve skill to get its name for the response\n      const skill = await skills.get(identifier);\n      if (!skill) {\n        throw new HTTPException(404, { message: `Skill \"${identifier}\" not found` });\n      }","sourceCodeStart":1038,"sourceCodeEnd":1074,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workspace.ts#L1038-L1074","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Include both skillName and referencePath in the request (path/query as documented in the route).","Check for undefined/empty variables before constructing the URL on the client side.","Match the exact parameter names the route expects (skillName, referencePath, optional path)."],"exampleFix":"// before\nconst url = `/workspaces/ws1/skills/${undefined}/references/${ref}`\n// after\nif (!skillName || !referencePath) throw new Error('skillName and referencePath required');\nconst url = `/workspaces/ws1/skills/${encodeURIComponent(skillName)}/references/${encodeURIComponent(referencePath)}`;","handlingStrategy":"validation","validationCode":"if (!skillName?.trim() || !referencePath?.trim()) {\n  throw new Error('Both skillName and referencePath are required before calling the reference API');\n}","typeGuard":"function hasRequiredRefParams(p: { skillName?: string; referencePath?: string }): p is { skillName: string; referencePath: string } {\n  return typeof p.skillName === 'string' && p.skillName.length > 0 && typeof p.referencePath === 'string' && p.referencePath.length > 0;\n}","tryCatchPattern":"try {\n  return await client.getSkillReference({ skillName, referencePath });\n} catch (e) {\n  if (isHttpException(e, 400)) throw new Error('Client bug: missing skillName/referencePath — check URL construction');\n  throw e;\n}","preventionTips":["Build URLs via a typed client helper rather than string interpolation.","Assert non-empty inputs in tests for URL builders.","Keep parameter names in sync with the route definition."],"tags":["http-400","validation","skills","rest-api"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}