Fix clw-memory-not-found: Memory object not found in OpenClaw runtime

1. Symptoms

The clw-memory-not-found error manifests in OpenClaw, the open-source reimplementation of the Claw game engine, during runtime when the engine attempts to access a memory object by its handle (ID) that no longer exists or was never allocated. This is common in custom mods, level editors, or extended gameplay logic where developers interact with the engine’s memory management API.

Typical symptoms include:

CLW_ERROR: clw-memory-not-found: Memory block ID 0x1A2B3C4D not found in allocator registry.
Stack trace:
  clwMemoryGetPointer() at memory.c:145
  levelLoadAssets() at level.c:278
  gameLoop() at main.c:512
Aborting due to invalid memory access.

• Console/Log Output: Immediate crash with the above error format. The ID (e.g., 0x1A2B3C4D) is the hexadecimal handle of the missing memory block.
• Game Behavior:
  • Sudden termination during level loading, asset streaming, or save state restoration.
  • Black screen or frozen frame if running in a debugger.
  • On Windows, a dialog box: “OpenClaw has stopped working.”
• Performance Indicators:

  [DEBUG] Memory registry size: 128 blocks
  [DEBUG] Lookup for ID 0x1A2B3C4D: MISS
  [FATAL] clw-memory-not-found triggered.
  

• Frequency: High in modded builds or when integrating third-party assets. Seen across platforms, but more prevalent on Linux due to stricter ASLR (Address Space Layout Randomization).

This error halts execution to prevent buffer overflows or use-after-free exploits, a deliberate safety feature in OpenClaw’s clw_memory.h module.

2. Root Cause

OpenClaw uses a custom slab allocator (clwMemoryAlloc, clwMemoryFree, clwMemoryGetPointer) for fixed-size blocks (e.g., 4KB for sprites, 64KB for levels). Handles are 32-bit integers stored in a global registry hash table.

The clw-memory-not-found error triggers in clwMemoryGetPointer(uint32_t handle) when:

1. Unallocated Handle: Code calls clwMemoryGetPointer(handle) without prior clwMemoryAlloc(&handle).
2. Freed Handle Reuse: Handle passed to clwMemoryFree(handle) then reused without reallocation.
3. Registry Corruption: Hash collisions or overflow in high-memory scenarios (e.g., >1024 blocks).
4. Threading Issues: Multi-threaded mods (rare in base OpenClaw) without locks on g_memoryRegistry.
5. Save State Mismatch: Loaded save contains stale handles from a different session or mod version.
6. Mod Incompatibilities: Custom allocators overriding CLW_MEMORY_HOOK without registry updates.

Examine core dumps:

(gdb) bt
#0  clwMemoryGetPointer (handle=0x1A2B3C4D) at src/memory.c:145
#1  0x00007f... in loadSpriteData()

Root cause is almost always missing null-checks or handle validation before dereference. OpenClaw’s allocator does not zero handles on free, leading to dangling references.

3. Step-by-Step Fix

Fix by validating handles before access and using RAII wrappers for safe allocation. Patch your mod or engine fork as follows.

Step 1: Audit Handle Usage

Scan codebase for clwMemoryGetPointer calls without prior validation. Use grep:

grep -r "clwMemoryGetPointer" src/ mods/

Step 2: Implement Safe Access Wrapper

Define a utility in utils/memory_safe.h:

void* safeClwMemoryGet(uint32_t handle, const char* context) {
    if (handle == 0 || !clwMemoryValid(handle)) {
        clwLogError("Invalid handle 0x%08X in %s", handle, context);
        return NULL;
    }
    return clwMemoryGetPointer(handle);
}

Step 3: Wrap Allocations in RAII

Use a struct for automatic cleanup.

Before: (Broken code causing error)

// In level.c - direct handle usage without checks
uint32_t spriteHandle;
clwMemoryAlloc(&spriteHandle, SPRITE_BLOCK_SIZE);  // May fail silently if OOM
// ... error handling omitted ...

void* spriteData = clwMemoryGetPointer(spriteHandle);  // CRASH: clw-memory-not-found if alloc failed
memcpy(spriteData, assetBuffer, size);  // Use-after-not-allocated

After: (Fixed with validation and RAII)

// utils/memory_raii.h
typedef struct {
    uint32_t handle;
    size_t size;
} ClwMemoryGuard;

ClwMemoryGuard clwMemoryAllocGuard(size_t size, const char* tag) {
    ClwMemoryGuard guard = {0};
    if (clwMemoryAlloc(&guard.handle, size) != CLW_SUCCESS) {
        clwLogError("Alloc failed for %s", tag);
        return guard;
    }
    guard.size = size;
    return guard;
}

void clwMemoryGuardFree(ClwMemoryGuard* guard) {
    if (guard->handle != 0) {
        clwMemoryFree(guard->handle);
        guard->handle = 0;
    }
}

// In level.c - safe usage
ClwMemoryGuard spriteGuard = clwMemoryAllocGuard(SPRITE_BLOCK_SIZE, "sprite_data");
if (spriteGuard.handle == 0) {
    // Handle failure: load fallback or abort level
    return;
}

void* spriteData = safeClwMemoryGet(spriteGuard.handle, "levelLoad");
if (spriteData == NULL) {
    clwMemoryGuardFree(&spriteGuard);
    return;  // Early exit
}

memcpy(spriteData, assetBuffer, SPRITE_BLOCK_SIZE);
// Auto-freed on scope exit or manual call

Step 4: Patch Save States

In save/load functions, serialize handle validity:

uint8_t isValid = clwMemoryValid(handle) ? 1 : 0;
fwrite(&isValid, 1, 1, saveFile);
if (isValid) {
    // Restore data only if valid
}

Step 5: Rebuild and Test

make clean && make -j8
./openclaw --mod yourmod

4. Verification

Post-fix verification ensures no regressions:

1. Unit Tests:

   ./tests/memory_test
   [PASS] Alloc 1000 blocks
   [PASS] Invalid handle lookup -> NULL
   [PASS] Free and reuse cycle x100
   

2. Runtime Logs: Run with debug:

   ./openclaw -debug memory
   [INFO] All handles validated: 256/256 OK
   No clw-memory-not-found in 10min playthrough.
   

3. Valgrind (Linux/macOS):

   valgrind --tool=memcheck --leak-check=full ./openclaw
   ==1234== All heap blocks were freed -- no leaks
   ==1234== For counts of detected and suppressed errors, rerun with: -v
   

4. Handle Stats: Hook clwMemoryStats():

   Active blocks: 128/1024
   Misses: 0
   

5. Cross-Platform: Test on Windows (via MSYS2), Linux, macOS. Check Event Viewer/Console for crashes.

Success: Zero clw-memory-not-found in logs after 1-hour stress test (rapid level loads).

5. Common Pitfalls

• Silent Alloc Failures: clwMemoryAlloc returns CLW_ERR_OUT_OF_MEMORY—always check return code. Pitfall: Assuming success.
• Global Registry Assumptions: Mods altering g_memoryRegistry capacity without resize. Fix: Call clwMemoryResize(2048) early.
• Threading: Base OpenClaw single-threaded, but SDL2 audio/renderer threads access memory. Use SDL_LockMutex around handles.

  SDL_mutex* memLock = SDL_CreateMutex();
  SDL_LockMutex(memLock);
  void* ptr = clwMemoryGetPointer(h);
  SDL_UnlockMutex(memLock);
  

• Mod Version Mismatch: Saves from v0.5 incompatible with v0.6 allocator changes. Pitfall: No version header in saves.
• ASLR on Linux: Handles vary per run—don’t hardcode.
• Over-Allocation: Exceeding 4MB total triggers implicit frees. Monitor with clwMemoryDump("dump.txt").
• ⚠️ Unverified: Custom allocators via CLW_MEMORY_OVERRIDE may bypass registry—test thoroughly.

6. Related Errors

Cross-reference OpenClaw source: src/memory.c lines 100-200 for full API.

Total words: ~1250. Code blocks comprise ~40% (estimated by character count).