TencentCloud/TencentDB-Agent-Memory · error · KernelFetchError

KernelFetchError(504 on timeout, 502 otherwise) with dynamic

Error message

KernelFetchError(504 on timeout, 502 otherwise) with dynamic failure message

What it means

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.

Source

Thrown at MemoryPanel/src/panel/kernel/transport-fetch.ts:228

      request_id: envelope.request_id,
      responseBody: serializeForLog(env.data ?? {}),
    });
    return (env.data ?? {}) as T;
  } catch (err) {
    if (err instanceof KernelFetchError) throw err;
    const isTimeout = (err as { name?: string }).name === 'AbortError';
    const message = isTimeout
      ? `remote metadata timeout at ${path}`
      : `remote metadata call failed at ${path}: ${(err as Error).message}`;
    const code = isTimeout ? 504 : 502;
    logRemoteMeta(log, 'error', reqId, {
      path,
      durationMs: Date.now() - startedAt,
      request_id: reqId,
      envelopeCode: code,
      error: message,
    });
    throw new KernelFetchError(code, message);
  } finally {
    clearTimeout(timer);
  }
}

View on GitHub (pinned to 3efcd317b8)

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

Example fix

// before
const env = await executeMetaFetch(ctx, path, body);
// after
try { const env = await executeMetaFetch(ctx, path, body); }
catch (e) {
  if (e instanceof KernelFetchError && e.code === 504) throw new Error(`kernel timeout on ${path}; increase timeout or check kernel health`);
  throw e;
}

Defensive patterns

Strategy: retry

Validate before calling

const started = Date.now();
const healthy = await fetch(`${kernelBaseUrl}/health`, { signal: AbortSignal.timeout(2000) });
if (!healthy.ok) throw new Error(`kernel unhealthy before call (HTTP ${healthy.status})`);

Type guard

class KernelFetchError extends Error {
  constructor(public code: number, message: string) { super(message); }
}
function isKernelFetchError(e: unknown): e is KernelFetchError {
  return e instanceof KernelFetchError;
}

Try / catch

try {
  return await executeMetaFetch(ctx, path, body);
} catch (e) {
  if (isKernelFetchError(e) && (e.code === 504 || e.code === 502)) {
    return retryWithBackoff(() => executeMetaFetch(ctx, path, body), { attempts: 3 });
  }
  throw e;
}

Prevention

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

When it happens

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

Common situations: 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.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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