# How to Troubleshoot TencentDB Agent Memory Connection Issues: 8 Debug Steps

> Troubleshoot TencentDB Agent Memory connection issues with 8 debug steps. Enable verbose logging and trace requests to quickly resolve HTTP gateway or LLM resolver failures.

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

---

**Enable verbose logging via `LOG_LEVEL=debug` and trace requests through [`guard-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/guard-adapter.ts) and [`pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/pipeline-manager.ts) to isolate connection failures in the HTTP gateway or LLM resolver.**

TencentDB-Agent-Memory is a distributed memory system for AI agents composed of loosely-coupled HTTP services. When you troubleshoot TencentDB Agent Memory connection issues, you need to trace requests through the **MemoryProxy**, **MemoryCore gateway**, and **Pipeline Manager** to identify where the flow breaks.

## Understand the Component Architecture

Before debugging, map your request path to these source files:

- **MemoryCore gateway** ([`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts)) – The entrypoint HTTP server that routes requests to skill handlers.
- **MemoryProxy** ([`MemoryProxy/src/guard-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/guard-adapter.ts)) – The reverse-proxy layer that handles cost-guarding and telemetry forwarding via `resolveForwardTarget`.
- **Pipeline Manager** ([`MemoryCore/src/utils/pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-manager.ts)) – Orchestrates L1/L2/L3 processing queues and logs state transitions.
- **Serial Queue** ([`MemoryCore/src/utils/serial-queue.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/serial-queue.ts)) – The FIFO queue implementation with debug hooks used by the pipeline manager.
- **LLM Provider Resolver** ([`MemoryCore/src/adapters/standalone/llm-provider-resolver.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/adapters/standalone/llm-provider-resolver.ts)) – Resolves API keys and model configurations for L1 extraction.
- **CLI Utilities** (`MemoryCore/bin/seed-v2.mjs`) – Scripts for seeding test data and inspecting local memory stores.

## Enable Verbose Logging Globally

All internal components respect the `LOG_LEVEL` environment variable. Setting it to `debug` activates the `logger?.debug?.` calls scattered throughout the codebase, including lines 277–388 in [`pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/pipeline-manager.ts) and lines 4–12 in [`guard-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/guard-adapter.ts).

```bash
export LOG_LEVEL=debug
export TDAI_GATEWAY_CONFIG=./tdai-gateway.standalone.yaml
export TDAI_GATEWAY_API_KEY="your-strong-token"
node --import tsx MemoryCore/src/gateway/server.ts

```

Debug logs reveal queue enqueue operations, passthrough decisions, and quota checks, giving you a step-by-step trace of a request’s journey through the system.

## Verify the HTTP Gateway Health

Confirm the gateway process is listening and responsive by querying the health endpoint.

```bash
curl -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" http://127.0.0.1:8420/health

# Expected: {"status":"ok"}

```

Non-200 responses indicate binding errors or authentication failures. Check the startup logs for `TDAI_GATEWAY_HOST` and `TDAI_GATEWAY_PORT` configuration issues in the resolved configuration.

## Trace Requests Through the MemoryProxy

When a request hits the proxy, `resolveForwardTarget` in [`guard-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/guard-adapter.ts) (lines 4–13) decides between direct passthrough or guarded routing:

- **Passthrough** – Logged as `guard_adapter.passthrough` with a `reason` field.
- **Guarded** – Subsequent logs show `extension_unavailable` if the cost-guard extension is missing.

If you suspect the guard is interfering with connections, bypass it:

```bash
export TDAI_COST_GUARD_ENABLED=false

```

Watch the logs change from *extension_disabled* to *default_passthrough*, confirming the proxy is not blocking your request.

## Inspect Pipeline Queue State

The pipeline manager maintains three independent queues (`l1Queue`, `l2Queue`, `l3Queue`). With `LOG_LEVEL=debug`, the manager wires debug loggers at lines 287–292 in [`pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/pipeline-manager.ts):

```ts
if (this.logger?.debug) {
  const debugFn = (msg: string) => this.logger?.debug?.(`${TAG} ${msg}`);
  this.l1Queue.setDebugLogger(debugFn);
  this.l2Queue.setDebugLogger(debugFn);
  this.l3Queue.setDebugLogger(debugFn);
}

```

Look for these log patterns to identify stalls:

- `[l1-debug] Enqueuing L1 (queue=queue-name)` – Request entered L1 extraction.
- `[l1-debug] L1 already queued, skipping` – Indicates a stuck L1 process, often due to a malformed conversation payload or missing LLM runner.
- `[l3-debug] L3 complete` – Request finished processing.

If L1 extraction hangs, verify that [`pipeline-factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/pipeline-factory.ts) (lines 408–453) is not emitting “No OpenClaw config and no LLM runner, skipping L1 extraction.”

## Validate Configuration Precedence

Configuration resolution follows a strict order. If you encounter unexpected defaults, verify which file is loaded:

1. `TDAI_GATEWAY_CONFIG` environment variable (highest priority).
2. [`tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.yaml) in the current directory.
3. [`tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.yaml) in the data directory.

Print the resolved configuration at runtime:

```bash
node --import tsx -e "console.log(require('./MemoryCore/src/config').loadConfig())"

```

The loader implementation lives in [`MemoryCore/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/config.ts) and clarifies precedence between environment variables and YAML files.

## Check Skill Module and LLM Connectivity

Skill-related endpoints (`/v3/skill/*`) depend on the LLM provider resolver. If L1 extraction fails, check that the resolver can locate a valid `TDAI_LLM_API_KEY` and model configuration in [`adapters/standalone/llm-provider-resolver.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/adapters/standalone/llm-provider-resolver.ts).

When the cost-guard extension is enabled, telemetry flows through `forwardTelemetry` in [`guard-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/guard-adapter.ts) (lines 42–48). Ensure destination URLs like Opik or Langfuse are reachable; missing tokens surface as HTTP 401 errors in the proxy logs.

## Use CLI Utilities for Data Inspection

Two built-in commands help establish a baseline:

- **Read local memory** – Dumps recent conversation records from the SQLite store.

  ```bash
  npm run read-local-memory
  ```

- **Seed V2** – Loads a deterministic dataset for reproducible debugging.

  ```bash
  npm run seed-v2
  ```

Both commands respect the same environment configuration as the gateway, allowing you to compare clean runs against problematic states using `MemoryCore/bin/seed-v2.mjs`.

## Summary

- Set `LOG_LEVEL=debug` to activate granular tracing in [`pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/pipeline-manager.ts) and [`guard-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/guard-adapter.ts).
- Query `/health` with your `TDAI_GATEWAY_API_KEY` to verify gateway availability.
- Analyze `guard_adapter.passthrough` logs to determine if the proxy or cost-guard is blocking requests.
- Monitor `[l1-debug]`, `[l2-debug]`, and `[l3-debug]` messages to pinpoint pipeline stalls.
- Validate that `TDAI_LLM_API_KEY` is configured and the resolver in [`llm-provider-resolver.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/llm-provider-resolver.ts) can initialize the LLM runner.
- Use `npm run seed-v2` and `npm run read-local-memory` for deterministic reproduction and data inspection.

## Frequently Asked Questions

### Why is my TencentDB Agent Memory gateway returning 401 Unauthorized?

The gateway requires the `Authorization: Bearer` header matching your `TDAI_GATEWAY_API_KEY`. Verify the header is present and the token matches the value used at startup. Check the gateway logs for [`guard-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/guard-adapter.ts) entries indicating token validation failures.

### How do I disable the cost-guard extension to rule out proxy issues?

Set the environment variable `TDAI_COST_GUARD_ENABLED=false` before starting the gateway. This forces [`guard-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/guard-adapter.ts) to use default passthrough mode, bypassing the private cost-guard extension and its telemetry forwarding to external services.

### What causes “No OpenClaw config and no LLM runner, skipping L1 extraction”?

This error in [`pipeline-factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/pipeline-factory.ts) (lines 408–453) indicates the system cannot locate a valid LLM configuration. Ensure `TDAI_LLM_API_KEY` is exported and that [`adapters/standalone/llm-provider-resolver.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/adapters/standalone/llm-provider-resolver.ts) can resolve your model provider. Without an LLM runner, L1 memory extraction is skipped, breaking downstream processing.

### How can I check if the pipeline queues are processing requests?

Enable `LOG_LEVEL=debug` and look for `[l1-debug] Enqueuing L1` and `[l3-debug] L3 complete` in the logs. If you see `[l1-debug] L1 already queued, skipping` repeatedly, the L1 queue is stuck, usually due to a hanging LLM call or malformed payload in the serial queue.