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

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. 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.

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 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.

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 (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.

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 (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.

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 (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 (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.

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) 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) 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 when JSON parsing fails or the code field is missing from responses.
• Database warnings in agents/asset-import.ts log SQLite access issues but allow continued execution, potentially causing downstream failures.
• Stream errors in 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 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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}