brainy/docs/vfs/TROUBLESHOOTING.md

VFS Troubleshooting Guide

Common Issues and Solutions

Issue: "VFSError: Not a directory: /"

Symptoms:

• readdir('/') throws "Not a directory" error
• Root directory exists but isn't recognized as directory
• Files can be written but not listed

Root Cause: The root directory entity exists but doesn't have the proper metadata structure.

Solution: This issue has been fixed. The VFS now:

1. Ensures root directory has vfsType: 'directory' metadata
2. Adds compatibility layer for entities with malformed metadata
3. Automatically repairs metadata on entity retrieval

Manual Fix (if needed):

// Force re-initialization of root directory
await vfs.init() // Will repair root if needed

// Or manually update root entity
const rootId = vfs.rootEntityId
await brain.update({
 id: rootId,
 metadata: {
 path: '/',
 vfsType: 'directory',
 // ... other metadata
 }
})

---

Issue: "readdir() returns empty array despite files existing"

Symptoms:

• Files are successfully written to VFS
• Files can be read individually
• readdir() returns [] for directories with files

Root Cause: Contains relationships are missing between parent directories and files.

Solution: This issue has been fixed. The VFS now:

1. Creates Contains relationships when writing new files
2. Ensures Contains relationships exist when updating files
3. Repairs missing relationships automatically

Manual Fix (if needed):

// Repair missing Contains relationship
const parentId = await vfs.resolvePath('/directory')
const fileId = await vfs.resolvePath('/directory/file.txt')

await brain.relate({
 from: parentId,
 to: fileId,
 type: VerbType.Contains
})

---

Issue: "VFS not initialized" error

Symptoms:

• Any VFS operation throws "VFS not initialized"
• Operations fail even after creating VFS instance

Root Cause: The VFS init() method wasn't called after getting the VFS instance.

Solution:

// ✅ CORRECT
const vfs = brain.vfs() // Get instance
await vfs.init() // Initialize (REQUIRED!)

// ❌ WRONG
const vfs = brain.vfs()
// Missing: await vfs.init()

---

Issue: Files disappear after process restart

Symptoms:

• Files exist during session
• All files gone after restart
• Fresh VFS each time

Root Cause: Using in-memory storage instead of persistent storage.

Solution:

// ✅ Use persistent storage
const brain = new Brainy({
 storage: {
 type: 'filesystem', // Persistent
 path: './brainy-data'
 }
})

// ❌ Don't use memory for production
const brain = new Brainy({
 storage: { type: 'memory' } // Data lost on restart!
})

---

Issue: Infinite recursion when listing directories

Symptoms:

• Directory appears as its own child
• Stack overflow errors
• UI freezes

Root Cause: Using path-based filtering instead of graph relationships.

Solution:

// ✅ CORRECT - Use graph relationships
const children = await vfs.getDirectChildren('/directory')

// ❌ WRONG - Path prefix matching causes recursion
const allNodes = await brain.find({})
const children = allNodes.filter(n =>
 n.metadata.path.startsWith('/directory/')) // Directory matches itself!

---

Issue: Can't find files by content

Symptoms:

• Semantic search returns no results
• Only exact filename matches work

Root Cause: Files aren't being properly embedded or indexed.

Solution:

// Ensure files have content for embedding
await vfs.writeFile('/doc.txt', 'Actual content here') // Not empty!

// Use semantic search correctly
const results = await vfs.search('machine learning', {
 path: '/documents', // Search within path
 limit: 10,
 type: 'file'
})

---

Debugging Tips

1. Check VFS Initialization

console.log('VFS initialized:', vfs.initialized)
console.log('Root entity ID:', vfs.rootEntityId)

2. Verify Entity Metadata

const entity = await vfs.getEntity('/path/to/file')
console.log('Entity metadata:', entity.metadata)
console.log('VFS type:', entity.metadata.vfsType)

3. Check Relationships

const parentId = await vfs.resolvePath('/directory')
const relations = await brain.related({
 from: parentId,
 type: VerbType.Contains
})
console.log('Child count:', relations.length)

4. Enable Debug Logging

const brain = new Brainy({
 storage: { type: 'filesystem' },
 logger: {
 level: 'debug',
 enabled: true
 }
})

---

Performance Tips

1. Use Caching

// Enable caching in VFS config
const vfs = brain.vfs({
 cache: {
 enabled: true,
 ttl: 300000, // 5 minutes
 maxSize: 1000
 }
})

2. Batch Operations

// Write multiple files efficiently
const files = [
 { path: '/file1.txt', content: 'content1' },
 { path: '/file2.txt', content: 'content2' }
]

await Promise.all(
 files.map(f => vfs.writeFile(f.path, f.content))
)

3. Limit Directory Depth

// Don't traverse too deep
const tree = await vfs.getTreeStructure('/', {
 maxDepth: 3, // Limit recursion
 includeHidden: false
})

---

Getting Help

If you encounter issues not covered here:

1. Check the VFS API Guide
2. Review Common Patterns
3. Look at test files for working examples
4. Report issues at GitHub Issues

Remember: Most VFS issues are related to:

• Missing initialization (await vfs.init())
• Using memory storage instead of filesystem
• Missing Contains relationships
• Incorrect path handling