{"record":{"id":"305880ee33fb1418","repo":"mastra-ai/mastra","slug":"expected-an-array-of-route-segments","errorCode":null,"errorMessage":"expected an array of route segments","messagePattern":"expected an array of route segments","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"deployers/vercel/src/index.ts","lineNumber":83,"sourceCode":"        );\n      }\n\n      this.injectStudioConfig(staticDir);\n    }\n  }\n\n  /**\n   * Studio's top-level route segments, emitted by the Studio build alongside index.html.\n   * The Vercel route table needs them explicitly: custom `registerApiRoute()` paths are mounted\n   * at the root of the server, so the function has to own every path Studio doesn't claim.\n   */\n  private readStudioRouteRoots(studioSource: string): string[] {\n    const manifestPath = join(studioSource, 'routes-manifest.json');\n\n    try {\n      const roots = JSON.parse(readFileSync(manifestPath, 'utf-8'));\n      if (!Array.isArray(roots) || roots.some(root => typeof root !== 'string')) {\n        throw new Error('expected an array of route segments');\n      }\n      return roots;\n    } catch (err) {\n      throw new Error(\n        `Failed to read studio routes manifest at \"${manifestPath}\": ${err instanceof Error ? err.message : err}`,\n      );\n    }\n  }\n\n  private getEntry(): string {\n    return `\nimport { handle } from 'hono/vercel'\nimport { mastra } from '#mastra';\nimport { createHonoServer, getToolExports } from '#server';\nimport { tools } from '#tools';\nimport { scoreTracesWorkflow } from '@mastra/core/evals/scoreTraces';\n\nif (mastra.getStorage()) {","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/vercel/src/index.ts#L65-L101","documentation":"readStudioRouteRoots parses studio's routes-manifest.json and requires it to be a JSON array of strings (route segments). If the parsed value is not an array or contains non-string entries, this sentinel error is thrown, then immediately re-wrapped by the catch block as 'Failed to read studio routes manifest...'.","triggerScenarios":"routes-manifest.json contains an object, a string, or an array of numbers/objects instead of an array of strings; produced by a studio build with an incompatible or corrupted manifest format.","commonSituations":"Version mismatch between the deployer and the studio build outputting a new manifest shape; a hand-edited or truncated manifest file; a stale manifest from a previous build.","solutions":["Rebuild the studio to regenerate a correct routes-manifest.json.","Open routes-manifest.json and confirm it is an array of strings like [\"api\",\"agents\"].","Check for a deployer/studio version mismatch and upgrade the deployer.","Delete the manifest and rerun the studio build to rule out stale output."],"exampleFix":"// before (routes-manifest.json)\n{ \"routes\": [\"api\"] }\n// after\n[\"api\", \"agents\"]","handlingStrategy":"validation","validationCode":"import { readFileSync } from 'node:fs';\nconst manifest = JSON.parse(readFileSync(join(studioSource, 'routes-manifest.json'), 'utf-8'));\nconst isValid = Array.isArray(manifest) && manifest.every(r => typeof r === 'string');\nif (!isValid) throw new Error('routes-manifest.json must be an array of strings');","typeGuard":"function isRouteRoots(value: unknown): value is string[] {\n  return Array.isArray(value) && value.every((r): r is string => typeof r === 'string');\n}","tryCatchPattern":"try {\n  await deployer.prepare();\n} catch (err) {\n  if (String((err as Error).message).includes('routes manifest')) {\n    console.error('Manifest missing or malformed — rebuild the studio:', (err as Error).message);\n  }\n  throw err;\n}","preventionTips":["Keep deployer and studio package versions in sync.","Rebuild the studio after any upgrade so the manifest shape matches.","Don't hand-edit routes-manifest.json.","Validate the manifest shape once at build time in CI."],"tags":["deployer","vercel","manifest","schema-validation"],"backgroundTag":"schema-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}