mastra-ai/mastra · error · HTTPException

Reference "${decodedPath}" not found in skill "${identifier}

Error message

Reference "${decodedPath}" not found in skill "${identifier}"

What it means

After validating the decoded path, the handler calls `skills.getReference(identifier, 'references/<decodedPath>')`. When the skill exists but the referenced file does not, getReference returns null and the handler throws a 404 naming the reference path and skill.

Source

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

        throw new HTTPException(404, { message: `Skill "${identifier}" not found` });
      }

      // Decode the reference path (it may be URL encoded)
      let decodedPath: string;
      try {
        decodedPath = decodeURIComponent(referencePath);
      } catch {
        throw new HTTPException(400, { message: 'Malformed referencePath' });
      }

      // Prevent path traversal via the reference path parameter
      assertSafeFilePath(decodedPath);

      // getReference expects a path relative to skill.path, so prepend 'references/'
      // since the URL path already contains the literal /references/ segment
      const content = await skills.getReference(identifier, `references/${decodedPath}`);
      if (content === null) {
        throw new HTTPException(404, {
          message: `Reference "${decodedPath}" not found in skill "${identifier}"`,
        });
      }

      return {
        skillName: skill.name,
        referencePath: decodedPath,
        content,
      };
    } catch (error) {
      return handleWorkspaceError(error, 'Error getting skill reference');
    }
  },
});

export const WORKSPACE_SEARCH_SKILLS_ROUTE = createRoute({
  method: 'GET',
  path: '/workspaces/:workspaceId/skills/search',

View on GitHub (pinned to 75dd419e61)

Solutions

List the skill's references (skills.listReferences / the references listing endpoint) and use an exact file path.
Remember the path is relative to the skill's references/ directory — do not prepend 'references/' yourself.
Check the file exists in the skill package on disk and was deployed.
Fix the file extension/case to match the actual file.

Example fix

// before
GET /skills/my-skill/references/Reference.md
// after
GET /skills/my-skill/references/reference.md

Defensive patterns

Strategy: try-catch

Validate before calling

const refs = await client.listSkillReferences(workspaceId, identifier);
if (!refs.includes(decodedPath)) {
  throw new Error(`Reference "${decodedPath}" unavailable; have: ${refs.join(', ')}`);
}

Type guard

function referenceExists(refs: string[], path: string): boolean {
  return refs.includes(path.replace(/^\/+/, ''));
}

Try / catch

try {
  return await client.getSkillReference({ skillName, referencePath });
} catch (e) {
  if (isHttpException(e, 404)) {
    const refs = await client.listSkillReferences(workspaceId, skillName);
    console.warn(`Missing reference. Available: ${refs}`);
    return null;
  }
  throw e;
}

Prevention

List references before fetching; treat the list as the source of truth.
Do not prepend 'references/' yourself — the route does it.
Match file names and extensions exactly, including case.

When it happens

Trigger: GET .../skills/:identifier/references/:referencePath where the decoded path does not correspond to a file under the skill's references/ directory, or it was rejected earlier by assertSafeFilePath (path traversal) — though traversal has its own error, a null return here means simply 'no such reference file'.

Common situations: Typo in the reference filename; wrong file extension (.txt vs .md); reference file deleted or not shipped with the skill; requesting a path outside references/ assuming root-relative paths.

Related errors

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