{"record":{"id":"32e842b93b356b7a","repo":"TencentCloud/TencentDB-Agent-Memory","slug":"kernelfetcherror-504-on-timeout-502-otherwise-wi","errorCode":null,"errorMessage":"KernelFetchError(504 on timeout, 502 otherwise) with dynamic failure message","messagePattern":"KernelFetchError\\(504 on timeout, 502 otherwise\\) with dynamic failure message","errorType":"http","errorClass":"KernelFetchError","httpStatus":502,"severity":"error","filePath":"MemoryPanel/src/panel/kernel/transport-fetch.ts","lineNumber":228,"sourceCode":"      request_id: envelope.request_id,\n      responseBody: serializeForLog(env.data ?? {}),\n    });\n    return (env.data ?? {}) as T;\n  } catch (err) {\n    if (err instanceof KernelFetchError) throw err;\n    const isTimeout = (err as { name?: string }).name === 'AbortError';\n    const message = isTimeout\n      ? `remote metadata timeout at ${path}`\n      : `remote metadata call failed at ${path}: ${(err as Error).message}`;\n    const code = isTimeout ? 504 : 502;\n    logRemoteMeta(log, 'error', reqId, {\n      path,\n      durationMs: Date.now() - startedAt,\n      request_id: reqId,\n      envelopeCode: code,\n      error: message,\n    });\n    throw new KernelFetchError(code, message);\n  } finally {\n    clearTimeout(timer);\n  }\n}\n","sourceCodeStart":210,"sourceCodeEnd":233,"githubUrl":"https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/3efcd317b84146d6a08518ac0f7ee7c8a8d200ec/MemoryPanel/src/panel/kernel/transport-fetch.ts#L210-L233","documentation":"executeMetaFetch is the transport layer for meta-kernel calls over fetch. After retries/timeouts are exhausted it throws KernelFetchError carrying an envelope code and message: 504 when the request timed out (internal AbortController timer fired), 502 when the upstream returned a failure or non-ok status. The message is dynamic (timeout duration, upstream error text) and is also logged with path, duration and request_id.","triggerScenarios":"Meta-kernel HTTP endpoint not responding before the timeout deadline (→ 504); kernel returning non-2xx or a non-zero envelope code after retries (→ 502); connection refused/reset mid-request; abort due to the per-request timer.","commonSituations":"Kernel service overloaded or hung during heavy asset imports; wrong port/host after a config change; long-running kernel invocations exceeding the fixed forward timeout; kernel restarting during deploys.","solutions":["Read error.code (504 = timeout, 502 = upstream failure) and error.message plus the logged request_id to locate the kernel-side cause","Increase the transport timeout if kernel calls legitimately exceed the deadline","Check kernel service health/logs for the logged request_id and path","Retry with backoff for 502/504 if the operation is idempotent"],"exampleFix":"// before\nconst env = await executeMetaFetch(ctx, path, body);\n// after\ntry { const env = await executeMetaFetch(ctx, path, body); }\ncatch (e) {\n  if (e instanceof KernelFetchError && e.code === 504) throw new Error(`kernel timeout on ${path}; increase timeout or check kernel health`);\n  throw e;\n}","handlingStrategy":"retry","validationCode":"const started = Date.now();\nconst healthy = await fetch(`${kernelBaseUrl}/health`, { signal: AbortSignal.timeout(2000) });\nif (!healthy.ok) throw new Error(`kernel unhealthy before call (HTTP ${healthy.status})`);","typeGuard":"class KernelFetchError extends Error {\n  constructor(public code: number, message: string) { super(message); }\n}\nfunction isKernelFetchError(e: unknown): e is KernelFetchError {\n  return e instanceof KernelFetchError;\n}","tryCatchPattern":"try {\n  return await executeMetaFetch(ctx, path, body);\n} catch (e) {\n  if (isKernelFetchError(e) && (e.code === 504 || e.code === 502)) {\n    return retryWithBackoff(() => executeMetaFetch(ctx, path, body), { attempts: 3 });\n  }\n  throw e;\n}","preventionTips":["Use idempotent kernel operations when retrying on 502/504","Right-size the timeout for the heaviest kernel invocation","Alert on KernelFetchError rate to catch kernel degradation early","Correlate via the logged request_id when contacting kernel owners"],"tags":["network","timeout","transport","meta-kernel"],"backgroundTag":"upstream-timeout","analyzedSha":"3efcd317b84146d6a08518ac0f7ee7c8a8d200ec","analyzedAt":"2026-09-01T05:44:22.276Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}