{"record":{"id":"17cc93b9a6f28ef9","repo":"slidevjs/slidev","slug":"cannot-action-the-first-slide-of-the-entry-file","errorCode":null,"errorMessage":"Cannot ${action} the first slide of the entry file: its frontmatter is the deck headmatter (global configuration). Edit its content with the update tool instead, or operate on the following slides.","messagePattern":"Cannot (.+?) the first slide of the entry file: its frontmatter is the deck headmatter \\(global configuration\\)\\. Edit its content with the update tool instead, or operate on the following slides\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/slidev/node/mcp/operations.ts","lineNumber":27,"sourceCode":" * throw a descriptive error.\n */\nexport function resolveSlide(data: LoadedSlidevData, no: number): SlideInfo {\n  const slide = data.slides[no - 1]\n  if (!slide)\n    throw new Error(`Slide ${no} does not exist. The deck has ${data.slides.length} slides (1-${data.slides.length}).`)\n  return slide\n}\n\nfunction getMarkdown(data: LoadedSlidevData, source: SourceSlideInfo) {\n  const md = data.markdownFiles[source.filepath]\n  if (!md)\n    throw new Error(`Markdown file not loaded: ${source.filepath}`)\n  return md\n}\n\nfunction assertNotEntryHeadmatter(data: LoadedSlidevData, source: SourceSlideInfo, action: string) {\n  if (source.filepath === data.entry.filepath && data.entry.slides.indexOf(source) === 0) {\n    throw new Error(\n      `Cannot ${action} the first slide of the entry file: its frontmatter is the deck headmatter (global configuration). `\n      + `Edit its content with the update tool instead, or operate on the following slides.`,\n    )\n  }\n}\n\nexport interface SlidePatchResult {\n  slide: SlideInfo\n  fileContent: string\n}\n\n/**\n * Apply a `SlidePatch` to the slide source and save the markdown file.\n *\n * Note this only mutates the *source* slide (`slide.source`), not the\n * rendered `SlideInfo`, so a running dev server will pick up the change from\n * disk like an external edit and push HMR updates to connected clients.\n */","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/slidevjs/slidev/blob/0d798ace5828966d9f77f62094d5f7a971ad98f7/packages/slidev/node/mcp/operations.ts#L9-L45","documentation":"Thrown by assertNotEntryHeadmatter when the target slide is slide #1 of the entry file. That slide's frontmatter doubles as the deck-wide headmatter (global config like theme, fonts, transitions), so removing, moving, or inserting before it would corrupt global configuration. The error directs callers to the update tool instead.","triggerScenarios":"Calling slidev-remove-slide with no:1 of the entry file, slidev-move-slide with from:1 (or before:1) on the entry file, or any operation routed through assertNotEntryHeadmatter whose source is entry.slides[0].","commonSituations":"An agent tries to delete the title slide; user wants to reorder the opening slide to the middle; inserting a slide before the deck's first slide.","solutions":["Use slidev-update-slide on slide 1 to change its content/frontmatter instead of removing or moving it.","To reorder, move the slide you want first into position 1's content rather than relocating slide 1 itself.","If slide 1 truly must go, edit the entry markdown by hand to merge/drop the headmatter block, then reload."],"exampleFix":"// before: trying to remove the title slide of slides.md\nawait tools['slidev-remove-slide']({ no: 1 }) // throws\n\n// after: rewrite slide 1 content via update instead\nawait tools['slidev-update-slide']({ no: 1, content: '# New Title' })","handlingStrategy":"validation","validationCode":"function isEntryHeadmatter(data: LoadedSlidevData, source: SourceSlideInfo): boolean {\n  return source.filepath === data.entry.filepath\n    && data.entry.slides.indexOf(source) === 0\n}\n\n// guard remove/move/insert-before:\nif (isEntryHeadmatter(data, slide.source)) {\n  // route the caller to slidev-update-slide instead\n  throw new Error('Use slidev-update-slide for the deck headmatter slide.')\n}","typeGuard":"function isProtectedHeadmatterSlide(\n  data: LoadedSlidevData,\n  source: SourceSlideInfo,\n): source is SourceSlideInfo {\n  return isEntryHeadmatter(data, source)\n}","tryCatchPattern":"try {\n  await removeSlide(data, no)\n} catch (e) {\n  if (e instanceof Error && e.message.includes('deck headmatter')) {\n    // fall back to update-slide for slide 1, or guide the user\n    return { error: 'Slide 1 is the deck headmatter; use slidev-update-slide to change it.' }\n  }\n  throw e\n}","preventionTips":["Never target slide #1 of the entry file with remove/move/insert-before.","For reordering the deck opening, edit content of slide 1 rather than relocating it.","In agent prompts, state explicitly that slide 1 is immutable for structural ops.","If restructuring is unavoidable, edit the entry markdown by hand and reload."],"tags":["mcp","headmatter","entry-file","configuration"],"backgroundTag":null,"analyzedSha":"0d798ace5828966d9f77f62094d5f7a971ad98f7","analyzedAt":"2026-08-12T17:10:56.221Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}