TencentCloud/TencentDB-Agent-Memory · error

${TAG} ${path} envelope error ${env.code}: ${env.message ??

Error message

${TAG} ${path} envelope error ${env.code}: ${env.message ?? ""}

What it means

The metadata service returned HTTP 200 but its JSON envelope carried a non-zero business code (env.code !== 0), so fetch throws with the path, code, and server message. This is the library's signal for application-level errors that arrive inside a successful HTTP response.

Source

Thrown at MemoryProxy/src/meta/client.ts:559

    } catch (err) {
      throw new Error(`${TAG} ${path} fetch failed: ${(err as Error).message}`);
    }

    if (!resp.ok) {
      let detail = "";
      try {
        detail = await resp.text();
      } catch { /* ignore */ }
      console.log(
        `[wb-debug] metadata-client req path=${path} status=${resp.status} url=${url} serviceId=${this.serviceId} userKey.len=${this.userKey?.length ?? 0} userKey.prefix=${(this.userKey ?? "").slice(0, 20)} serviceToken.len=${this.serviceToken?.length ?? 0} body.len=${detail.length} body.head=${detail.slice(0, 300)}`,
      );
      throw new Error(`${TAG} ${path} HTTP ${resp.status}${detail ? `: ${detail.slice(0, 200)}` : ""}`);
    }

    const env = (await resp.json()) as CoreEnvelope<T>;

    if (env.code !== 0) {
      throw new Error(`${TAG} ${path} envelope error ${env.code}: ${env.message ?? ""}`);
    }

    if (env.data === null || env.data === undefined) {
      throw new Error(`${TAG} ${path} unexpected null data`);
    }

    return env.data as T;
  }
}

// ── Singleton + test injection ──────────────────────────────────────────────

let _client: MetadataClient | null = null;
let _clientKey = "";
let _forced = false;

function clientKey(cfg: Pick<CoreSkillConfig, "endpoint" | "serviceToken" | "timeoutMs">, serviceId: string, userKey: string): string {
  return `${cfg.endpoint}::${cfg.serviceToken}::${serviceId}::${cfg.timeoutMs}::${userKey}`;

View on GitHub (pinned to 3efcd317b8)

Solutions

  1. Read env.code and env.message from the error text and look up the code in the metadata service API docs
  2. Fix the request payload per the server's message (usually the authoritative cause)
  3. Check tenant/project quotas and permissions on the service side
  4. Handle specific business codes in calling code (retryable vs permanent) instead of blanket retries

Example fix

// before
await client.updateTask(id, { status: "closed" }); // envelope error 1201: task already closed
// after
const task = await client.getTask(id);
if (task.status !== "closed") await client.updateTask(id, { status: "closed" });
Defensive patterns

Strategy: try-catch

Validate before calling

// check resource state before mutating
def validateTaskUpdate(task, patch) {
  if (task.status === "closed" && patch.status) throw new Error("cannot update closed task");
}

Try / catch

try {
  await client.appendParticipationLog(entry);
} catch (e) {
  const m = /envelope error (\d+):\s*(.*)$/.exec(e.message);
  if (m) {
    const [code, msg] = [Number(m[1]), m[2]];
    if (RETRYABLE_ENVELOPE_CODES.has(code)) await backoffRetry();
    else console.error(`metadata rejected: code=${code} msg=${msg}`);
  } else throw e;
}

Prevention

When it happens

Trigger: createTask/updateTask/appendParticipationLog receives a CoreEnvelope with code != 0 — e.g. business validation rejection, permission denied at the application layer, quota exceeded, or duplicate resource.

Common situations: Server-side validation rules rejecting payloads that pass client-side checks; tenant quotas exhausted; operations on resources in a state that disallows the mutation (e.g. updating a closed task).

Related errors

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