What causes "Invalid REPL directory specified: "${directory}"" in gatsbyjs/gatsby?

Invalid REPL directory specified: "${directory}"

Error message

Invalid REPL directory specified: "${directory}"

What it means

In gatsby-remark-code-repls createPages (gatsby-node.js:27-29), the plugin checks fs.existsSync(directory) after normalizing the directory option (defaulting to OPTION_DEFAULT_REPL_DIRECTORY, appending '/' if missing). If the directory does not exist on disk, reporter.panic fires. The directory is where the plugin looks for .js/.jsx files to create interactive CodePen REPL redirect pages.

Source

Thrown at packages/gatsby-remark-code-repls/src/gatsby-node.js:28

  OPTION_DEFAULT_CODEPEN,
} = require(`./constants`)

exports.createPages = async (
  { actions, reporter },
  {
    directory = OPTION_DEFAULT_REPL_DIRECTORY,
    codepen = OPTION_DEFAULT_CODEPEN,
  } = {}
) => {
  codepen = { ...OPTION_DEFAULT_CODEPEN, ...codepen }
  if (!directory.endsWith(`/`)) {
    directory += `/`
  }

  const { createPage } = actions

  if (!fs.existsSync(directory)) {
    reporter.panic(`Invalid REPL directory specified: "${directory}"`)
  }

  if (!fs.existsSync(codepen.redirectTemplate)) {
    reporter.panic(
      `Invalid REPL redirectTemplate specified: "${codepen.redirectTemplate}"`
    )
  }

  try {
    const files = await readdir(directory)
    if (files.length === 0) {
      console.warn(`Specified REPL directory "${directory}" contains no files`)

      return
    }

    // escape backslashes for windows
    const resolvedDirectory = resolve(directory)

View on GitHub (pinned to 8b06340921)

Solutions

Create the directory: mkdir -p <your-directory>
Verify the path: use an absolute path to avoid cwd ambiguity
Check for typos in the directory option

Example fix

// before: directory doesn't exist
options: { directory: `./src/examples` }
// if ./src/examples doesn't exist → panic

// after: create it first, or fix the path
mkdir -p src/examples
// or point to the correct existing path
options: { directory: `${__dirname}/src/examples` }

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs')
const path = require('path')

const replDirectory = path.resolve(process.cwd(), options.directory || './src/examples')
if (!fs.existsSync(replDirectory)) {
  throw new Error(`REPL directory does not exist: ${replDirectory}. Create it before building.`)
}
if (!fs.statSync(replDirectory).isDirectory()) {
  throw new Error(`REPL path is not a directory: ${replDirectory}`)
}

Type guard

import fs from 'fs'
import path from 'path'

function isValidDirectory(dirPath: string): boolean {
  const resolved = path.resolve(dirPath)
  return fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()
}

Prevention

Create the examples directory before configuring the plugin
Use absolute paths for the directory option
Add directory existence checks to a pre-build script

When it happens

Trigger: Configuring gatsby-remark-code-repls with a 'directory' option that doesn't exist. The default directory constant points to a path that hasn't been created. Typo in the directory path.

Common situations: Setting directory to a custom path that hasn't been created. Using the plugin without setting up the expected examples/examples directory. Path relative to cwd resolving to a non-existent location.

Related errors

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/e2a379f5452981f4. Report an issue: GitHub.