# Common Errors When Using TencentDB Agent Memory: A Complete Troubleshooting Guide

> Troubleshoot common TencentDB Agent Memory errors like missing environment variables ParamError and TDAMError. Fix runtime failures with this complete guide.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-25

---

**The most frequent runtime failures in TencentDB Agent Memory stem from missing environment variables in `loadConfigFromEnv`, invalid arguments raising `ParamError`, and service-side issues surfaced as `TDAMError` with specific numeric codes like 40901 or 41002.**

TencentDB Agent Memory (also referenced as TD AI Memory) is an open-source TypeScript/Node.js SDK suite available in the TencentCloud/TencentDB-Agent-Memory repository that manages AI memory contexts through HTTP/JSON envelopes. Understanding the three-layer error hierarchy—**configuration**, **validation**, and **transport**—is essential for debugging common errors when using TencentDB Agent Memory effectively.

## Configuration Errors from Missing Environment Variables

The SDK validates required settings during initialization via the `loadConfigFromEnv` function in [`agents/asset-import.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/asset-import.ts). According to the source code at lines 81–89, this function throws a generic `Error` when any of the three mandatory environment variables are absent: `PANEL_URL`, `TDAI_SERVICE_ID`, or `TDAI_USER_KEY`.

Unlike validation errors that provide structured feedback, configuration failures terminate execution immediately with a standard JavaScript `Error` object. This typically manifests during agent startup before any network requests occur.

```typescript
import { loadConfigFromEnv } from "./agents/asset-import.js";

(async () => {
  try {
    const cfg = await loadConfigFromEnv(); // May throw generic Error
    console.log("Config loaded:", cfg);
  } catch (e) {
    console.error("Configuration error:", e.message);
    process.exit(1);
  }
})();

```

## Parameter Validation Failures and ParamError

Client-side validation errors are handled by the custom `ParamError` class, defined in [`sdk/memory-core/typescript/src/errors.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/errors.ts) at lines 5–9. This specialized error extends `TypeError` and is thrown when method arguments contain empty strings, missing required fields, or invalid list structures.

The `MemoryClient` and `SkillClient` implementations in `sdk/memory-core/typescript/src/v3/` perform these checks before transmitting requests. Catching `ParamError` allows you to handle malformed inputs without attempting network operations.

```typescript
import { MemoryClient, ParamError } from "sdk/memory-core/typescript/src/v3/client.js";

const client = new MemoryClient({ apiKey: "sk-...", serviceId: "svc-001" });

try {
  // Empty string triggers ParamError
  await client.createMemoryPrompt({ name: "", prompt: "SELECT 1" });
} catch (e) {
  if (e instanceof ParamError) {
    console.error("Parameter problem:", e.message);
  }
}

```

## API Transport Errors and TDAMError

HTTP communication failures are managed in [`sdk/memory-core/typescript/src/http.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/http.ts) (lines 31–38). The transport layer performs two critical validations:

1. **Parsing validation**: If the server returns non-JSON data or a missing `code` field, the wrapper throws a generic `Error`.
2. **Service validation**: When the envelope contains a numeric `code` property not equal to `0`, the SDK instantiates `TDAMError` with the service error code, message, request ID, and optional `details` object.

This distinction is crucial for distinguishing between network-level failures and application-level service rejections.

```typescript
import { MemoryClient, TDAMError } from "sdk/memory-core/typescript/src/v3/client.js";

(async () => {
  try {
    await client.updateSkill({ skillId: "s-123", version: 2, body: {} });
  } catch (e) {
    if (e instanceof TDAMError) {
      console.error(`TDAM error ${e.code}: ${e.message}`, e.requestId);
    }
  }
})();

```

## Skill Version Conflicts and Error Codes

Version mismatches represent specific service-side error conditions identified by numeric codes. According to [`sdk/memory-core/typescript/src/errors.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/errors.ts) (lines 18–22), the `TDAMError` class preserves an extended `details` field specifically to support conflict resolution scenarios.

Common skill-related error codes include:

- **40901**: `SKILL_VERSION_STALE` — The provided version is outdated but recoverable
- **41002**: `SKILL_VERSION_EXPIRED` — The skill version is no longer valid

These errors include structured data in the `details` property, such as `current_version`, enabling programmatic conflict resolution without additional API calls.

```typescript
try {
  await client.updateSkill({ skillId: "s-123", version: 2 });
} catch (e) {
  if (e instanceof TDAMError && e.code === 40901) {
    console.log("Stale version detected. Current:", e.details.current_version);
    // Implement retry logic with updated version
  }
}

```

## Database State and SQLite Warnings

The `MemoryKnowledge` component in [`agents/asset-import.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/asset-import.ts) (lines 2395–2415) manages local state persistence via SQLite. When the agent fails to open or read the local `state.db` file, the startup code logs a warning message and continues execution rather than throwing an exception.

Downstream operations may subsequently encounter generic `Error` messages containing Chinese text such as "无法打开 state.db" (unable to open state.db). These warnings indicate filesystem permission issues or corrupted database files that require manual intervention to resolve.

## Workbuddy Streaming Timeouts

Stream processing errors occur in [`MemoryProxy/src/workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/workbuddyHandler.ts) (lines 677–686) during Workbuddy integration. When a stream encounters a timeout or unexpected termination, the handler logs the specific error context and re-throws a generic `Error` with a descriptive message.

These failures typically indicate network instability between the memory proxy and the Workbuddy service, or prolonged processing times exceeding configured timeouts.

## Implementing Robust Error Handling

To handle common errors when using TencentDB Agent Memory effectively, implement a catch block that checks the error hierarchy: `Error` → `ParamError` → `TDAMError`. This pattern distinguishes between configuration issues, client mistakes, and service responses.

```typescript
import { ParamError, TDAMError } from "sdk/memory-core/typescript/src/errors.js";

try {
  // Any Memory SDK method call
  await client.createMemoryPrompt({ name: "query", prompt: "SELECT * FROM users" });
} catch (e) {
  if (e instanceof ParamError) {
    console.error("Invalid argument:", e.message);
    // Handle validation - check input formats
  } else if (e instanceof TDAMError) {
    console.error(`Service error ${e.code}: ${e.message}`, e.details);
    // Handle service logic - check error codes, retry if necessary
  } else {
    console.error("System failure:", e);
    // Handle transport/config - check network, env vars, DB state
  }
}

```

## Summary

- **Configuration failures** occur in `loadConfigFromEnv` ([`agents/asset-import.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/asset-import.ts)) when `PANEL_URL`, `TDAI_SERVICE_ID`, or `TDAI_USER_KEY` are missing, throwing generic `Error` objects.
- **Validation errors** raise `ParamError` (defined in [`sdk/memory-core/typescript/src/errors.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/errors.ts)) for malformed arguments like empty strings or invalid lists.
- **Service errors** surface as `TDAMError` with numeric codes (e.g., 40901, 41002) and include `requestId` and `details` fields for debugging version conflicts and business logic failures.
- **Transport errors** happen in [`sdk/memory-core/typescript/src/http.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/http.ts) when JSON parsing fails or the `code` field is missing from responses.
- **Database warnings** in [`agents/asset-import.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/asset-import.ts) log SQLite access issues but allow continued execution, potentially causing downstream failures.
- **Stream errors** in [`MemoryProxy/src/workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/workbuddyHandler.ts) indicate timeout conditions during Workbuddy operations.

## Frequently Asked Questions

### What is the difference between ParamError and TDAMError in TencentDB Agent Memory?

**ParamError** is a client-side validation error defined in [`sdk/memory-core/typescript/src/errors.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/errors.ts) that extends `TypeError` and indicates malformed method arguments detected before any network request occurs. **TDAMError** is a service-response error representing failures returned by the TencentDB Agent Memory API, identified by numeric codes like 40901 or 41002, and includes metadata such as `requestId` and `details` for server-side debugging.

### How do I fix "无法打开 state.db" warnings when starting the agent?

This warning originates in [`agents/asset-import.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/asset-import.ts) (lines 2395–2415) when the `MemoryKnowledge` component cannot access the local SQLite database. Resolve this by verifying filesystem permissions for the agent's working directory, ensuring adequate disk space, and checking that no other process has locked the `state.db` file. The warning logs but does not halt execution, so verify downstream functionality if the warning persists.

### What do error codes 40901 and 41002 indicate in the TencentDB Agent Memory SDK?

Code **40901** (`SKILL_VERSION_STALE`) indicates your provided skill version is outdated but recoverable, allowing you to retry with updated parameters found in the `TDAMError.details` field. Code **41002** (`SKILL_VERSION_EXPIRED`) indicates the skill version is no longer valid and requires creating a new version or updating to a current release before retrying the operation.

### How should I handle missing environment variables when configuring the agent?

Wrap the `loadConfigFromEnv()` call from [`agents/asset-import.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/asset-import.ts) in a try-catch block that catches generic `Error` instances, as this function throws standard errors rather than custom classes when `PANEL_URL`, `TDAI_SERVICE_ID`, or `TDAI_USER_KEY` are undefined. Implement a fallback configuration loader or terminate the process with a clear exit code to prevent runtime failures in production environments.