EISDIR error when creating/adding observations for directory paths (client reads directory as a file)

[punkyard]

Summary

While creating entities or adding observations with the memory MCP server, we observed intermittent EISDIR errors when entity names corresponded to directory paths (e.g., .github). The error is triggered when a client or server attempts to read a directory as if it were a file and fails with Node's EISDIR error.

Environment

• Node: 24.x (example from workspace: v24.11.1)
• npx: 11.x
• Memory server: @modelcontextprotocol/server-memory
• Workspace: firstb00t-v2 (project-level analysis performed on: /Users/nmn/rez0/neimen/0-code/github-pun/firstb00t-v2)

Reproduction steps (simplified)

1. Stop the memory server or ensure it is unreachable.
2. From a client (or wrapper) call the memory MCP API create_entities or add_observations with an entity name that maps to an existing directory (e.g., .github) while not explicitly specifying entityType or specifying entityType incorrectly as file.
3. If the client attempts to read the path or infers the path as a file, fs.readFile will be invoked and an EISDIR error occurs: EISDIR: illegal operation on a directory, read <path>.

Observed

• Error message from Node: EISDIR: illegal operation on a directory, read <path>.
• The memory creation calls can partially succeed or fail — leading to inconsistent memory graph state.

Expected

• The MCP memory server or client should clearly handle directories and files separately.
  • For directories, either create an entity with entityType: "folder" or return a descriptive validation error asking the user to provide entityType: "folder".
  • For files, accept the request and, when specified, read file contents or add string observations without implicit filesystem reads.
• The client should not attempt to fallback to local filesystem reads when the memory server is offline; instead, return a connection error.

Potential root causes

• Client wrapper calls may attempt to read local file content automatically if a path-like name was provided (and entityType is not provided), and fs.readFile is invoked on a directory.
• Server-side may accept name as a raw string without proper validation or safe handling of directories vs. files.
• Server might accept wrong entityType values and not warning clearly.

Suggested fixes

1. Server-side validation
   • Validate the entityType upon /create_entities call and return clear, descriptive errors.
   • If entityType is not provided, return a validation error rather than attempting to infer a file read.
2. Client-side helper
   • Add a client wrapper that uses fs.stat() to check path type before any reads. If stat.isDirectory() return entityType: "folder" or raise a validation error.
   • If the server is offline, return a connection error and avoid falling back to local file reads.
3. Better logging
   • Add a more descriptive error message that indicates a directory path was provided and that a folder entity is required if that is intended.
4. Tests
   • Add unit/integration tests to validate behavior of both file & folder entityType creation, including offline server test to ensure no local file reads occur.

Attachments (from local analysis)

• .context/eisdir_analysis.md — local analysis of root cause for EISDIR error.
• .context/mem_import_2025-11-28.json — audit of entities & relations created while testing.
• .context/filetree.md — canonical file tree with clear folder/file separation.

Notes

• I can open a PR to add a client-side wrapper and tests if you want. Also happy to contribute a patch to server-side validation to make errors clearer.

[sstklen]

Hey! I ran into a similar pattern in our bug knowledge base and thought this might help.

What's happening: When entity names in the MCP memory server match existing directory paths (e.g., .github), the client or server incorrectly infers the entity name as a filesystem path and calls fs.readFile() on it. Node's fs.readFile() cannot read a directory, so it throws EISDIR: illegal operation on a directory, read. The memory server lacks a check to distinguish directories from files before performing file I/O, and does not validate that entity names should be treated as abstract identifiers rather than filesystem paths.

What worked for us:

Add a pre-flight fs.stat() or fs.lstat() check before any fs.readFile() call to determine whether the path is a directory. If it is a directory, either skip the read operation, create the entity with entityType: 'folder', or return a descriptive error instead of letting the raw EISDIR propagate. Additionally, entity names should be treated as abstract identifiers in the memory graph and not directly mapped to filesystem paths without validation.

Steps:

1. Before calling fs.readFile() on a path derived from an entity name, call fs.stat() to check if the path is a directory (stat.isDirectory())
2. If isDirectory() returns true, handle it gracefully: either set entityType to 'folder', skip the file read, or return a clear error message explaining directories cannot be read as files
3. Wrap the fs.readFile() call in a try/catch that specifically catches EISDIR errors (error.code === 'EISDIR') and converts them to a user-friendly error response instead of a crash
4. Consider decoupling entity names from filesystem path resolution entirely — entity names like '.github' should not trigger filesystem reads unless explicitly requested

// Before any fs.readFile(entityPath) call, add:
import { stat } from 'fs/promises';

async function safeReadEntity(entityPath: string): Promise<string> {
  try {
    const stats = await stat(entityPath);
    if (stats.isDirectory()) {
      throw new Error(
        `Cannot read '${entityPath}': it is a directory, not a file. ` +
        `Use entityType: 'folder' for directory entities.`
      );
    }
    return await fs.readFile(entityPath, 'utf-8');
  } catch (err: any) {
    if (err.code === 'EISDIR') {
      throw new Error(
        `EISDIR: '${entityPath}' is a directory. ` +
        `Set entityType to 'folder' or use a non-path entity name.`
      );
    }
    throw err;
  }
}

Hope this helps! Let me know if it doesn't match your case — happy to dig deeper. 🦞

Disclosure: This analysis is from Confucius Debug, an AI-powered community KB for agent bugs. Please verify before applying.

---

_{🦞 Confucius Debug — community knowledge base for AI agent bugs. Free to search via MCP.}

[olaservo]

The memory server never treats an entity name as a path; it only ever opens the file at MEMORY_FILE_PATH. An EISDIR on .github means the client, not the server, tried to read that name as a file. Closing as not a server issue. If you can reproduce it against the server alone with a JSON-RPC call and a stderr trace, please reopen.