slidevjs/slidev · error · Error

Cannot ${action} the first slide of the entry file: its fron

Error message

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.

What it means

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.

Source

Thrown at packages/slidev/node/mcp/operations.ts:27

 * throw a descriptive error.
 */
export function resolveSlide(data: LoadedSlidevData, no: number): SlideInfo {
  const slide = data.slides[no - 1]
  if (!slide)
    throw new Error(`Slide ${no} does not exist. The deck has ${data.slides.length} slides (1-${data.slides.length}).`)
  return slide
}

function getMarkdown(data: LoadedSlidevData, source: SourceSlideInfo) {
  const md = data.markdownFiles[source.filepath]
  if (!md)
    throw new Error(`Markdown file not loaded: ${source.filepath}`)
  return md
}

function assertNotEntryHeadmatter(data: LoadedSlidevData, source: SourceSlideInfo, action: string) {
  if (source.filepath === data.entry.filepath && data.entry.slides.indexOf(source) === 0) {
    throw new Error(
      `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.`,
    )
  }
}

export interface SlidePatchResult {
  slide: SlideInfo
  fileContent: string
}

/**
 * Apply a `SlidePatch` to the slide source and save the markdown file.
 *
 * Note this only mutates the *source* slide (`slide.source`), not the
 * rendered `SlideInfo`, so a running dev server will pick up the change from
 * disk like an external edit and push HMR updates to connected clients.
 */

View on GitHub (pinned to 0d798ace58)

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.

Example fix

// before: trying to remove the title slide of slides.md
await tools['slidev-remove-slide']({ no: 1 }) // throws

// after: rewrite slide 1 content via update instead
await tools['slidev-update-slide']({ no: 1, content: '# New Title' })

Defensive patterns

Strategy: validation

Validate before calling

function isEntryHeadmatter(data: LoadedSlidevData, source: SourceSlideInfo): boolean {
  return source.filepath === data.entry.filepath
    && data.entry.slides.indexOf(source) === 0
}

// guard remove/move/insert-before:
if (isEntryHeadmatter(data, slide.source)) {
  // route the caller to slidev-update-slide instead
  throw new Error('Use slidev-update-slide for the deck headmatter slide.')
}

Type guard

function isProtectedHeadmatterSlide(
  data: LoadedSlidevData,
  source: SourceSlideInfo,
): source is SourceSlideInfo {
  return isEntryHeadmatter(data, source)
}

Try / catch

try {
  await removeSlide(data, no)
} catch (e) {
  if (e instanceof Error && e.message.includes('deck headmatter')) {
    // fall back to update-slide for slide 1, or guide the user
    return { error: 'Slide 1 is the deck headmatter; use slidev-update-slide to change it.' }
  }
  throw e
}

Prevention

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.

When it happens

Trigger: 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].

Common situations: 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.

Related errors

AI-assisted analysis of slidevjs/slidev@0d798ace58 (2026-08-12). Data as JSON: /api/errors/17cc93b9a6f28ef9. Report an issue: GitHub.