mastraStudioLink: template must contain the {traceId} placeh

Error message

mastraStudioLink: template must contain the {traceId} placeholder

What it means

Error "mastraStudioLink: template must contain the {traceId} placeholder" thrown in JuliusBrussee/caveman.

Source

Thrown at packages/mastra/src/index.ts:786

export interface MastraStudioLinkOptions {
  /**
   * REQUIRED. Mastra documents a Studio Observability tab but not a per-trace
   * URL, so this package will not invent one. Supply the shape your Studio
   * build uses, with `{traceId}` (and optionally `{baseUrl}`) placeholders —
   * e.g. `"{baseUrl}/observability?traceId={traceId}"`.
   */
  template: string;
  /** Defaults to {@link MASTRA_STUDIO_DEFAULT_BASE_URL}. */
  baseUrl?: string;
}

/** Builds a Mastra Studio link from the caller-supplied template. */
export function mastraStudioLink(traceId: string, options: MastraStudioLinkOptions): string {
  const id = requireNonEmpty(traceId, "mastraStudioLink: traceId");
  const template = requireNonEmpty(options.template, "mastraStudioLink: template");
  if (!template.includes("{traceId}")) {
    throw new Error("mastraStudioLink: template must contain the {traceId} placeholder");
  }
  const baseUrl = trimTrailingSlashes(options.baseUrl ?? MASTRA_STUDIO_DEFAULT_BASE_URL);
  return template.replaceAll("{baseUrl}", baseUrl).replaceAll("{traceId}", encodeURIComponent(id));
}

/**
 * The Caveman dashboard trace page: `{baseUrl}/traces/{traceId}?project_id=…`.
 *
 * The dashboard currently resolves the project from the workspace switcher and
 * ignores the query parameter; it is carried so the link is unambiguous about
 * which project's trace it means.
 */
export function cavemanTraceLink(baseUrl: string, projectId: string, traceId: string): string {
  const base = requireBaseUrl(baseUrl, "cavemanTraceLink: baseUrl");
  const project = requireNonEmpty(projectId, "cavemanTraceLink: projectId");
  const trace = requireNonEmpty(traceId, "cavemanTraceLink: traceId");
  return `${base}/traces/${encodeURIComponent(trace)}?project_id=${encodeURIComponent(project)}`;
}

View on GitHub (pinned to 27d5a3981a)

Solutions

Include the {traceId} placeholder in the studio link template.

When it happens

Trigger: Thrown at packages/mastra/src/index.ts:786 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/9fe98ad7fb927859. Report an issue: GitHub.