{"record":{"id":"dae1e11068fc848f","repo":"TencentCloud/TencentDB-Agent-Memory","slug":"core-upstream-error","errorCode":"CORE_UPSTREAM_ERROR","errorMessage":"json.message || `core error code ${json.code}`","messagePattern":"json\\.message \\|\\| `core error code (.+?)`","errorType":"exception","errorClass":"CoreUpstreamError","httpStatus":502,"severity":"error","filePath":"MemoryPanel/src/panel/kernel/adapters/http-knowledge-client.ts","lineNumber":67,"sourceCode":"export class HttpKnowledgeClient implements KnowledgeClientPort {\n  constructor(private readonly cfg: KnowledgeClientConfig) {}\n\n  private async post<T>(path: string, body: unknown): Promise<T> {\n    const ctrl = new AbortController();\n    const timer = setTimeout(() => ctrl.abort(), this.cfg.timeoutMs ?? 15_000);\n    try {\n      const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n      if (this.cfg.authToken) headers.Authorization = `Bearer ${this.cfg.authToken}`;\n      if (this.cfg.serviceId) headers['x-tdai-service-id'] = this.cfg.serviceId;\n      const resp = await fetch(`${this.cfg.baseUrl}${path}`, {\n        method: 'POST',\n        headers,\n        body: JSON.stringify(body),\n        signal: ctrl.signal,\n      });\n      const json = (await resp.json()) as CoreEnvelope<T>;\n      if (json.code !== undefined && json.code !== 0) {\n        throw new CoreUpstreamError(\n          'CORE_UPSTREAM_ERROR',\n          resp.status >= 400 ? resp.status : 502,\n          json.message || `core error code ${json.code}`,\n          json.code,\n        );\n      }\n      if (!resp.ok) {\n        throw new CoreUpstreamError('CORE_UPSTREAM_ERROR', resp.status, json.message || `HTTP ${resp.status}`, 0);\n      }\n      return json.data as T;\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n\n  // ═══════════════ Wiki · 资产层 ═══════════════\n\n  async wikiCreate(teamId: string, name: string, userId?: string): Promise<WikiDetail> {","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/3efcd317b84146d6a08518ac0f7ee7c8a8d200ec/MemoryPanel/src/panel/kernel/adapters/http-knowledge-client.ts#L49-L85","documentation":"The HTTP knowledge client wraps every core (wiki) API call in an envelope check: when the JSON body carries a non-zero `code`, the client throws CoreUpstreamError('CORE_UPSTREAM_ERROR'). The HTTP status is mapped to resp.status when >= 400, otherwise 502, and the message is taken from the core's `message` field. This is the standard path for business-level failures returned by the core service.","triggerScenarios":"Any of wikiCreate, wikiGet, wikiIngest, wikiDelete, wikiList, wikiRawLs receiving a JSON envelope with code !== 0 and code !== undefined from the core HTTP endpoint — e.g. document not found, invalid ingest payload, auth rejection at the core level, or core-internal error with a JSON body.","commonSituations":"Core service returning structured error envelopes during downtime or schema changes; stale wiki document IDs after a core rebuild; core rejecting payloads after a version upgrade changed required fields.","solutions":["Read error.code and error.message from the thrown CoreUpstreamError and act on the specific core error code","Confirm the core service version matches what this client expects (schema drift)","Check core service logs for the request_id to find the underlying failure","Retry idempotent calls (wikiGet, wikiList) if the core code indicates a transient condition"],"exampleFix":"// before\ntry { await client.wikiIngest(body); } catch (e) { console.error(e); }\n// after\ntry { await client.wikiIngest(body); } catch (e) {\n  if (e instanceof CoreUpstreamError) console.error(`core code=${e.code} status=${e.status}: ${e.message}`);\n  else throw e;\n}","handlingStrategy":"try-catch","validationCode":"// pre-flight reachability check\nconst ping = await fetch(`${coreBaseUrl}/health`);\nif (!ping.ok) throw new Error(`core unreachable: HTTP ${ping.status}`);","typeGuard":"class CoreUpstreamError extends Error {\n  constructor(public name_: 'CORE_UPSTREAM_ERROR', public status: number, message: string, public code: number) { super(message); }\n}\nfunction isCoreUpstreamError(e: unknown): e is CoreUpstreamError {\n  return e instanceof CoreUpstreamError;\n}","tryCatchPattern":"try {\n  const doc = await client.wikiGet(id);\n} catch (e) {\n  if (isCoreUpstreamError(e)) {\n    console.error(`core error code=${e.code} http=${e.status}: ${e.message}`);\n  } else throw e;\n}","preventionTips":["Inspect e.code/e.status on CoreUpstreamError before generic handling","Keep core client and core service versions in sync","Health-check the core service before batch wiki operations","Retry only idempotent wiki calls (get/list) on transient codes"],"tags":["http","upstream","envelope-error"],"backgroundTag":"core-upstream-error","analyzedSha":"3efcd317b84146d6a08518ac0f7ee7c8a8d200ec","analyzedAt":"2026-09-01T05:44:22.276Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}