TencentCloud/TencentDB-Agent-Memory · error

Storage unavailable for instance ${instanceId}

Error message

Storage unavailable for instance ${instanceId}

What it means

OffloadTaskExecutor.resolveStorageOrThrow resolves a StorageAdapter for an offloaded session instance before reading/writing its state. If deps.resolveStorage returns undefined — meaning no storage backend is registered or reachable for that instanceId — the executor refuses to run the task because offload work is impossible without a store.

Source

Thrown at MemoryCore/src/offload_server/offload-task-executor.ts:667

  /**
   * Extract sessionId from task data or task.sessionId.
   */
  private extractSessionId(task: TaskPayload): string | undefined {
    const data = task.data as Record<string, unknown> | undefined;
    // Prefer explicit sessionId in data
    if (data?.sessionId && typeof data.sessionId === "string") {
      return data.sessionId;
    }
    // Fallback: task-level sessionId
    if (task.sessionId) {
      return task.sessionId;
    }
    return undefined;
  }

  private async resolveStorageOrThrow(instanceId: string): Promise<StorageAdapter> {
    const storage = await this.deps.resolveStorage(instanceId);
    if (!storage) throw new Error(`Storage unavailable for instance ${instanceId}`);
    return storage;
  }

  private async readState(storage: StorageAdapter, basePath: string): Promise<OffloadState> {
    const raw = await storage.readFile(`${basePath}/state.json`);
    if (!raw) return defaultOffloadState();
    try {
      return { ...defaultOffloadState(), ...JSON.parse(raw) };
    } catch {
      return defaultOffloadState();
    }
  }

  private async writeState(storage: StorageAdapter, basePath: string, state: OffloadState): Promise<void> {
    await storage.writeFile(`${basePath}/state.json`, JSON.stringify(state));
  }

  private findBoundaryByTimestamp(

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Verify resolveStorage has an adapter registered for this instanceId (check the resolver/deps wiring)
2. Re-register or recreate the instance's storage binding before re-enqueueing the task
3. Check storage backend health/config (credentials, endpoint) that may cause resolveStorage to return undefined
4. Add a guard to skip/park tasks for unknown instances instead of retrying indefinitely

Example fix

// before
const storage = await executor.run(task); // throws if storage gone
// after
const storage = await deps.resolveStorage(task.instanceId);
if (!storage) { await queue.park(task, 'storage-unavailable'); return; }

const storage = await deps.resolveStorage(instanceId);
if (!storage) { /* skip/park task */ }

try { await executor.run(task); } catch (e) { if (String(e.message).startsWith('Storage unavailable')) { await queue.park(task, 'storage-unavailable'); } else throw e; }

When it happens

Trigger: Executing an offload task (state restore/persist) whose instanceId has no registered storage adapter, e.g. the instance was deregistered, the storage plugin failed to initialize, or the resolver map lost the entry after a restart.

Common situations: Storage service down or not configured when offload tasks replay from a queue; instance IDs carried over from a previous deployment whose storage bindings were not migrated; race between instance eviction and a queued offload task.

Related errors

• Generation log object key exceeds COS limit
• Invalid generation log key
• Invalid generation log cursor
• Invalid scoped storage key: ${JSON.stringify(key)}
• Path traversal rejected in scoped storage key: ${key}

AI-assisted analysis of TencentCloud/TencentDB-Agent-Memory@3efcd317b8 (2026-09-01). Data as JSON: /api/errors/1eda83b2c1620a46. Report an issue: GitHub.