Error in gatsby-remark-code-repls plugin: cannot read

Error message

      Error in gatsby-remark-code-repls plugin: cannot read directory ${directory}.
      More details can be found in the error reporting below.

What it means

In gatsby-remark-code-repls createPages (gatsby-node.js:37-102), the plugin wraps the recursive readdir(directory) call and all file processing (reading, parsing, CSS matching, createPage) in a try-catch. If any operation throws — permission denied reading the directory, a file read error, a createPage error, or an error in the CSS matching logic — reporter.panic fires with the directory path and the original error object.

Source

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

          html: codepen.html,
          js: code,
          js_external: codepen.externals.join(`;`),
          js_pre_processor: `babel`,
          layout: `left`,
          css,
        })
        createPage({
          path: slug,
          component: normalizePath(resolve(codepen.redirectTemplate)),
          context: {
            action,
            payload,
          },
        })
      }
    })
  } catch (error) {
    reporter.panic(
      `
      Error in gatsby-remark-code-repls plugin: cannot read directory ${directory}.
      More details can be found in the error reporting below.
      `,
      error
    )
  }
}

View on GitHub (pinned to 8b06340921)

Solutions

Read the 'error' object in the panic output — it contains the specific underlying error (ENOENT, EACCES, EEXIST, etc.)
Fix file permissions: chmod -R +r <directory>
Remove or fix symlink loops in the directory
Rename duplicate files that create slug collisions
Ensure all files in the directory are valid and readable

Example fix

// before: permission issue or unreadable file
// Error output will show the specific error code

// after: fix permissions
chmod -R +r src/examples/
// or remove problematic files identified by the error

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-build: verify all files in the REPL directory are readable
const fs = require('fs')
const path = require('path')

function validateReplDirectory(dir) {
  const entries = fs.readdirSync(dir, { recursive: true })
  for (const entry of entries) {
    const fullPath = path.join(dir, entry)
    try {
      fs.accessSync(fullPath, fs.constants.R_OK)
    } catch {
      console.warn(`File not readable: ${fullPath}`)
    }
  }
}

Try / catch

// The plugin wraps the entire readdir+processing in try-catch.
// As a consumer, you can pre-validate file readability:
const files = fs.readdirSync(directory)
for (const file of files) {
  try {
    fs.readFileSync(path.join(directory, file), 'utf8')
  } catch (err) {
    console.error(`Cannot read ${file}:`, err.message)
  }
}

Prevention

Ensure all files in the REPL directory have read permissions (chmod +r)
Remove symlink loops or broken symlinks from the directory
Avoid duplicate file names that create slug collisions
Run a pre-build file validation check on the examples directory

When it happens

Trigger: Permission denied reading files in the directory. A file in the directory is not readable (locked, permission issue). recursive-readdir encounters a symlink loop or other file system error. createPage throws due to duplicate slugs or invalid page data. An error reading the matching CSS file (non-ENOENT errors from line 67's throw).

Common situations: File permission issues on the examples directory. Symlink loops causing readdir to fail. Duplicate file names creating slug collisions in createPage. Race condition where a file is deleted between readdir and readFileSync.

Related errors

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