Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

Summary

The memory-lancedb plugin fails to initialize when its data directory is bind-mounted to a Windows host path. This is due to file system sync delays between Windows and Docker containers when using bind mounts.

Environment

• Host OS: Windows 11
• Docker: Docker Desktop on Windows
• OpenClaw Version: 2026.3.24
• Plugin: memory-lancedb (bundled)
• LanceDB Version: @lancedb/lancedb ^0.27.1

Problem Description

When using a Windows bind mount for the LanceDB data directory, the plugin initialization fails with file metadata read errors. The same configuration works correctly when using a Docker volume.

Steps to reproduce

Failing Configuration

# docker-compose.yml - DOES NOT WORK on Windows
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:2026.3.24
    volumes:
      - C:\docker-data\lancedb:/app/.openclaw-data/lancedb  # Windows bind mount

Working Configuration

# docker-compose.yml - WORKS on Windows
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:2026.3.24
    volumes:
      - lancedb-data:/app/.openclaw-data/lancedb  # Docker volume

volumes:
  lancedb-data:

Steps to Reproduce

1. On Windows with Docker Desktop, create a docker-compose.yml with bind mount:

   volumes:
     - C:\docker-data\lancedb:/app/.openclaw-data/lancedb

2. Configure memory-lancedb plugin in openclaw.json:

   {
     "plugins": {
       "slots": { "memory": "memory-lancedb" },
       "entries": {
         "memory-lancedb": {
           "enabled": true,
           "config": {
             "embedding": {
               "baseUrl": "your-embedding-api-url",
               "apiKey": "your-api-key",
               "model": "your-embedding-model",
               "dimensions": 1024
             },
             "dbPath": "/app/.openclaw-data/lancedb",
             "autoCapture": true,
             "autoRecall": true
           }
         }
       }
     }
   }

3. Start container: docker compose up -d

4. Send a message that triggers memory capture

5. Observe error in logs

Expected behavior

openclaw could records memory through lancedb and works fine

Actual behavior

Error Logs

Initial Error (file not found)

[gateway] memory-lancedb: capture failed: Error: Table 'memories' was not found
Caused by: Dataset at path app/.openclaw-data/lancedb/memories.lance was not found
Not found: app/.openclaw-data/lancedb/memories.lance/_versions

Subsequent Error (metadata read failure)

[gateway] memory-lancedb: capture failed: Error: lance error: LanceError(IO): 
failed to read metadata for app/.openclaw-data/lancedb/memories.lance/data/110110111011110000001011fd1a194182894b4ab606bc70c1.lance: 
No such file or directory (os error 2)
/usr/local/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/lance-io-3.0.1/src/object_writer.rs:584:17

Permission Error (after partial file creation)

[gateway] memory-lancedb: recall failed: Error: lance error: LanceError(IO): 
Permission denied (os error 13)
/usr/local/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/lance-io-3.0.1/src/object_store.rs:669:21

Root Cause Analysis

The issue stems from LanceDB's write-then-immediately-read pattern during table initialization:

1. LanceDB behavior: When creating a table, LanceDB (written in Rust) writes data files and then immediately reads back metadata to verify the operation.

2. Windows Docker bind mount delay: When files are written to a Windows bind mount from inside a container, there's a synchronization delay between the Linux filesystem operations and the Windows NTFS filesystem.

3. Race condition: LanceDB tries to read the file it just wrote, but the metadata hasn't propagated through the bind mount layer yet, resulting in "No such file or directory" errors.

4. Why Docker volume works: Docker volumes are stored in Docker's internal Linux filesystem, which doesn't have the cross-filesystem synchronization delay.

OpenClaw version

2026.3.24

Operating system

• Host OS: Windows 11 - Docker: Docker Desktop on Windows - OpenClaw Version: 2026.3.24 - Plugin: memory-lancedb (bundled) - LanceDB Version: @lancedb/lancedb ^0.27.1

Install method

No response

Model

glm-5

Provider / routing chain

openclaw -> internal llm gateway -> z.ai

Additional provider/model setup details

No response

Logs, screenshots, and evidence

### Evidence

- Files ARE created on the Windows host (visible via File Explorer)
- But container cannot read them immediately after creation
- Same configuration works perfectly on Linux/macOS hosts
- Same configuration works with Docker volume on Windows

## Workaround

Use Docker volumes instead of bind mounts for LanceDB data:


services:
  openclaw:
    volumes:
      # Config files can still use bind mount (low frequency reads)
      - C:\docker-data\openclaw:/home/node/.openclaw
      # LanceDB data should use Docker volume (high frequency I/O)
      - lancedb-data:/app/.openclaw-data/lancedb

volumes:
  lancedb-data:

Impact and severity

Why Use Windows Bind Mount?

Users often prefer bind mounts for several reasons:

1. Data Visibility: Users can browse and inspect data files directly from Windows Explorer or other tools
2. Backup & Migration: Data is stored in a known location on the host, making it easier to backup or migrate
3. Persistence Guarantee: Even if Docker Desktop is uninstalled or Docker data is corrupted, the data in the bind-mounted directory remains intact
4. Development Convenience: During development, users may want to inspect or debug data files directly

This is a common pattern for developers who want full control over their data storage.

Additional information

Suggested Improvements

1. Documentation Update

Add a note in memory-lancedb documentation:

Windows Users: Due to file system synchronization delays, use Docker volumes instead of bind mounts for the LanceDB data directory. Bind mounts for config files are fine.

2. Plugin-Level Retry Mechanism

The memory-lancedb plugin could implement a retry mechanism during table initialization:

// In doInitialize()
const maxRetries = 3;
const retryDelay = 100; // ms

for (let attempt = 0; attempt < maxRetries; attempt++) {
  try {
    this.table = await this.db.createTable(TABLE_NAME, schemaRow);
    break;
  } catch (err) {
    if (attempt < maxRetries - 1) {
      await new Promise(resolve => setTimeout(resolve, retryDelay * (attempt + 1)));
    } else {
      throw err;
    }
  }
}

3. Improved Error Messages

Detect Windows environment and provide helpful error message:

LanceDB initialization failed. On Windows, this is often caused by using 
bind mounts for the data directory. Please try using a Docker volume instead:

volumes:
  lancedb-data:/app/.openclaw-data/lancedb

4. Default Path Change

Consider using a Docker-volume-friendly default path on Windows, or detecting the OS and adjusting behavior.

Related Information

• LanceDB version: 0.27.1
• LanceDB GitHub: https://github.com/lancedb/lancedb
• Similar issues may exist in other databases using write-then-read patterns (e.g., SQLite with WAL mode)

Verification

After switching to Docker volume, the plugin works correctly:

[gateway] memory-lancedb: initialized (db: /app/.openclaw-data/lancedb, model: jina-embeddings-v3)
[gateway] memory-lancedb: auto-captured 1 memories
[gateway] memory-lancedb: injecting 1 memories into context

Memory storage and recall function normally:

User: "Remember this: My favorite programming language is Python."
Response: "Got it, Shawn. I've noted that Python is your favorite programming language."

User: "What programming language do I like?"
Response: "You like Python!"

Thank you for considering this report. The workaround (Docker volume) resolves the issue, but documentation improvements would help other Windows users avoid the debugging time we spent.