packaged plugin contains an unsupported entry: ${entryPath}

Error message

packaged plugin contains an unsupported entry: ${entryPath}

What it means

Thrown by the packaged plugin resource verifier when an entry in the plugin tree is neither a regular file, a directory, nor a symbolic link. lstatSync returned metadata that fails all three checks (isSymbolicLink, isDirectory, isFile), indicating an exotic filesystem entry type such as a socket, FIFO (named pipe), character/block device, or other special file. These entry types are not meaningful in a packaged plugin and break content hashing (readFileSync would fail or block on them).

Source

Thrown at config/scripts/verify-packaged-plugin-resources.cjs:44

      const entryPath = join(directory, entry.name)
      const metadata = lstatSync(entryPath)
      entriesVisited += 1
      if (entriesVisited > MAX_PLUGIN_FILES) {
        throw new Error(`plugin exceeds the ${MAX_PLUGIN_FILES}-entry limit`)
      }
      if (metadata.isSymbolicLink()) {
        throw new Error(`packaged plugin contains a symlink: ${relative(root, entryPath)}`)
      }
      if (metadata.isDirectory()) {
        visit(entryPath)
      } else if (metadata.isFile()) {
        totalBytes += metadata.size
        if (totalBytes > MAX_PLUGIN_TOTAL_BYTES) {
          throw new Error(`plugin exceeds the ${MAX_PLUGIN_TOTAL_BYTES}-byte limit`)
        }
        files.push({ path: entryPath, size: metadata.size })
      } else {
        throw new Error(`packaged plugin contains an unsupported entry: ${entryPath}`)
      }
    }
  }
  visit(root)
  const hash = createHash('sha256').update('orca-plugin-tree-v1\0')
  for (const file of files) {
    const relativePath = relative(root, file.path).replaceAll('\\', '/')
    hashLength(hash, Buffer.byteLength(relativePath, 'utf8'))
    hash.update(relativePath, 'utf8')
    hashLength(hash, file.size)
    hash.update(readFileSync(file.path))
  }
  return hash.digest('hex')
}

function readJsonFile(path, label) {
  try {
    return JSON.parse(readFileSync(path, 'utf8'))

View on GitHub (pinned to 1136503c6a)

Solutions

Identify the unsupported entry from the error message (it includes the full path): file <entryPath> to determine its type.
Remove the special file from the plugin source tree.
Ensure the packaging step only copies regular files and directories: use rsync or tar with appropriate exclude filters.
Add a .gitignore or packaging exclusion for any path that generates special files during development.

Defensive patterns

Strategy: validation

Validate before calling

// Before packaging, scan for special (non-regular, non-directory) files.
const { execSync } = require('node:child_process')

function preCheckSpecialFiles(pluginRoot) {
  // Find files that are NOT regular files or directories (sockets, FIFOs, devices)
  try {
    const output = execSync(
      `find ${JSON.stringify(pluginRoot)} -type s -o -type p -o -type b -o -type c`,
      { encoding: 'utf8' }
    ).trim()
    return { ok: output.length === 0, specialFiles: output.split('\n').filter(Boolean) }
  } catch {
    return { ok: true, specialFiles: [] }
  }
}

Prevention

Clean the plugin directory before packaging: remove dev server sockets, IPC pipes, and other ephemeral files.
Use an explicit allowlist of files/directories to package rather than copying the entire source tree.
Run the packaging step in a clean CI environment where dev servers have not created artifacts.

When it happens

Trigger: hashPackagedPluginTree(root) encounters a special file during the recursive walk. This can happen when a development artifact (e.g., a Unix socket created by a dev server, a FIFO used for IPC) was inadvertently included in the packaged plugin tree.

Common situations: A hot-reload dev server or IPC mechanism left a socket file in the plugin directory; a build tool created a named pipe for streaming; packaging from a directory that contains OS-level device files (e.g., packaging from /dev or /tmp without cleanup); a broken packaging pipeline that copied special files.

Related errors

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/586f880a22eaeb22. Report an issue: GitHub.