akanjs 2.3.9-rc.3 → 2.3.9-rc.4

package/common/Logger.ts

@@ -2,12 +2,24 @@ import dayjs from "dayjs";
 
 const logLevels = ["trace", "verbose", "debug", "log", "info", "warn", "error"] as const;
 export type LogLevel = (typeof logLevels)[number];
+export type LoggerMeta = Record<string, unknown>;
+
+export interface LoggerSerializedError {
+  name?: string;
+  message: string;
+  stack?: string;
+  cause?: LoggerSerializedError | string;
+  digest?: string;
+  code?: string | number;
+  status?: number;
+}
 
 export interface LoggerSinkEntry {
   stream: "stdout" | "stderr";
   level?: LogLevel;
   message: string;
   plainMessage: string;
+  meta?: LoggerMeta;
 }
 
 export type LoggerSink = (entry: LoggerSinkEntry) => void | Promise<void>;
@@ -33,6 +45,11 @@ const colorizeMap: { [key in LogLevel]: (text: string) => string } = {
 
 const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
 
+function readErrorProp(error: unknown, key: string): unknown {
+  if (typeof error !== "object" || error === null || !(key in error)) return undefined;
+  return (error as Record<string, unknown>)[key];
+}
+
 /** Log-level aware logger used by Akan runtime, CLI, and application services. */
 export class Logger {
   static level: LogLevel = (process.env?.AKAN_PUBLIC_LOG_LEVEL as LogLevel | undefined) ?? "log";
@@ -86,6 +103,9 @@ export class Logger {
   error(msg: string, context = "", name = this.name ?? "App") {
     if (Logger.#shouldLog("error")) Logger.#printMessages(name, msg, context, "error");
   }
+  errorObject(msg: string, error: unknown, meta: LoggerMeta = {}, context = "", name = this.name ?? "App") {
+    if (Logger.#shouldLog("error")) Logger.#printError(name, msg, error, meta, context);
+  }
   raw(msg: string, method?: "console" | "process") {
     Logger.rawLog(msg, method);
   }
@@ -114,6 +134,60 @@ export class Logger {
   static error(msg: string, context = "", name = "App") {
     if (Logger.#shouldLog("error")) Logger.#printMessages(name, msg, context, "error");
   }
+  static errorObject(msg: string, error: unknown, meta: LoggerMeta = {}, context = "", name = "App") {
+    if (Logger.#shouldLog("error")) Logger.#printError(name, msg, error, meta, context);
+  }
+  static createErrorId(input: { requestId?: string; scope?: string; sequence?: string | number } = {}) {
+    const parts = ["akanerr", input.requestId, input.scope, input.sequence, Date.now().toString(36)]
+      .filter((part): part is string | number => part !== undefined && part !== "")
+      .map((part) => String(part).replace(/[^a-zA-Z0-9_-]/g, "-"));
+    return parts.join("-");
+  }
+  static serializeError(error: unknown): LoggerSerializedError {
+    if (error instanceof Error) {
+      const digest = readErrorProp(error, "digest");
+      const code = readErrorProp(error, "code");
+      const status = readErrorProp(error, "status") ?? readErrorProp(error, "statusCode");
+      return {
+        name: error.name,
+        message: error.message,
+        ...(error.stack ? { stack: error.stack } : {}),
+        ...(error.cause !== undefined ? { cause: Logger.serializeError(error.cause) } : {}),
+        ...(typeof digest === "string" ? { digest } : {}),
+        ...(typeof code === "string" || typeof code === "number" ? { code } : {}),
+        ...(typeof status === "number" ? { status } : {}),
+      };
+    }
+    if (typeof error === "object" && error !== null) {
+      const message = readErrorProp(error, "message");
+      const name = readErrorProp(error, "name");
+      const stack = readErrorProp(error, "stack");
+      const cause = readErrorProp(error, "cause");
+      const digest = readErrorProp(error, "digest");
+      const code = readErrorProp(error, "code");
+      const status = readErrorProp(error, "status") ?? readErrorProp(error, "statusCode");
+      return {
+        ...(typeof name === "string" ? { name } : {}),
+        message: typeof message === "string" ? message : String(error),
+        ...(typeof stack === "string" ? { stack } : {}),
+        ...(cause !== undefined ? { cause: Logger.serializeError(cause) } : {}),
+        ...(typeof digest === "string" ? { digest } : {}),
+        ...(typeof code === "string" || typeof code === "number" ? { code } : {}),
+        ...(typeof status === "number" ? { status } : {}),
+      };
+    }
+    return { message: String(error) };
+  }
+  static formatError(error: unknown) {
+    const serialized = Logger.serializeError(error);
+    const details = serialized.stack ?? serialized.message;
+    if (!serialized.cause) return details;
+    const cause =
+      typeof serialized.cause === "string"
+        ? serialized.cause
+        : (serialized.cause.stack ?? serialized.cause.message);
+    return `${details}\nCaused by: ${cause}`;
+  }
   static #colorize(msg: string, logLevel: LogLevel) {
     return colorizeMap[logLevel](msg);
   }
@@ -137,12 +211,18 @@ export class Logger {
       }
     }
   }
+  static #printError(name: string | undefined, msg: string, error: unknown, meta: LoggerMeta, context: string) {
+    const serializedError = Logger.serializeError(error);
+    const message = `${msg}: ${Logger.formatError(error)}`;
+    Logger.#printMessages(name, message, context, "error", "stderr", { ...meta, error: serializedError });
+  }
   static #printMessages(
     name: string | undefined,
     content: string,
     context: string,
     logLevel: LogLevel,
     writeStreamType: "stdout" | "stderr" = logLevel === "error" ? "stderr" : "stdout",
+    meta?: LoggerMeta,
   ) {
     const now = dayjs();
     const replicaIdx = (process as unknown as NodeJS.Process | undefined)?.env?.AKAN_REPLICA_IDX;
@@ -158,7 +238,7 @@ export class Logger {
     const timeDiffMsg = clc.yellow(`+${now.diff(Logger.#startAt, "ms")}ms`);
     const message = `${processMsg} ${timestampMsg} ${logLevelMsg} ${contextMsg} ${contentMsg} ${timeDiffMsg}\n`;
     if (Logger.#shouldEmitSink(logLevel))
-      Logger.#emit({ stream: writeStreamType, level: logLevel, message, plainMessage: Logger.#stripAnsi(message) });
+      Logger.#emit({ stream: writeStreamType, level: logLevel, message, plainMessage: Logger.#stripAnsi(message), meta });
     if (!Logger.#shouldWriteConsole(logLevel)) return;
     if (typeof window === "undefined")
       (process[writeStreamType] as unknown as NodeJS.WriteStream | undefined)?.write(message);

package/common/index.ts

@@ -17,7 +17,14 @@ export { isPhoneNumber } from "./isPhoneNumber";
 export { isQueryEqual } from "./isQueryEqual";
 export { isValidDate } from "./isValidDate";
 export { decodeJwtPayload } from "./jwtDecode";
-export { Logger, type LoggerSink, type LoggerSinkEntry, type LogLevel } from "./Logger";
+export {
+  Logger,
+  type LoggerMeta,
+  type LoggerSerializedError,
+  type LoggerSink,
+  type LoggerSinkEntry,
+  type LogLevel,
+} from "./Logger";
 export {
   type AkanI18nConfig,
   type AkanI18nConfigInput,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.3.9-rc.3",
+  "version": "2.3.9-rc.4",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/rscWorker.tsx

@@ -110,7 +110,7 @@ type InMsg = InitMsg | RenderMsg | CancelMsg | ReloadMsg | UpdateCssAssetsMsg |
 type RenderControl =
   | { type: "redirect"; location: string; method: "replace" | "push"; status: RedirectStatus }
   | { type: "not-found" }
-  | { type: "error"; error: unknown };
+  | { type: "error"; error: unknown; errorId: string; digest: string };
 interface FlightRenderResult {
   chunks: Uint8Array[];
   bytes: number;
@@ -206,6 +206,7 @@ export class RscRenderer {
   #resultCacheHits = 0;
   #resultCacheMisses = 0;
   #resultCacheBypass = 0;
+  #renderErrorSequence = 0;
   readonly #send: (message: unknown) => void;
 
   constructor() {
@@ -223,6 +224,74 @@ export class RscRenderer {
     this.#send({ type: "hello" });
   }
 
+  #nextRenderErrorId(requestId: string | undefined, scope: string): string {
+    this.#renderErrorSequence += 1;
+    return Logger.createErrorId({ requestId, scope, sequence: this.#renderErrorSequence });
+  }
+
+  #createRenderErrorPayload(
+    error: unknown,
+    input: {
+      requestId?: string;
+      scope: string;
+      errorId?: string;
+      url?: URL | string;
+      pathname?: string;
+      routeId?: string;
+      trace?: RscTraceMetadata;
+    },
+  ) {
+    const errorId = input.errorId ?? this.#nextRenderErrorId(input.requestId, input.scope);
+    const serialized = Logger.serializeError(error);
+    const pathname = input.pathname ?? input.trace?.pathname;
+    const routeId = input.routeId ?? input.trace?.routeId;
+    const url = typeof input.url === "string" ? input.url : input.url?.href;
+    const meta = {
+      errorId,
+      requestId: input.requestId,
+      scope: input.scope,
+      url,
+      pathname,
+      routeId,
+      digest: errorId,
+      originalDigest: serialized.digest,
+    };
+    return {
+      message: serialized.message,
+      name: serialized.name,
+      stack: serialized.stack,
+      errorId,
+      digest: errorId,
+      requestId: input.requestId,
+      scope: input.scope,
+      pathname,
+      routeId,
+      meta,
+    };
+  }
+
+  #logRenderError(
+    message: string,
+    error: unknown,
+    input: {
+      requestId?: string;
+      scope: string;
+      errorId?: string;
+      url?: URL | string;
+      pathname?: string;
+      routeId?: string;
+      trace?: RscTraceMetadata;
+    },
+  ) {
+    const payload = this.#createRenderErrorPayload(error, input);
+    this.#logger.errorObject(
+      `${message} requestId=${input.requestId ?? "(none)"} scope=${input.scope} errorId=${payload.errorId}`,
+      error,
+      payload.meta,
+    );
+    return payload;
+  }
+
   #handleMessage(msg: InMsg): void {
     switch (msg.type) {
       case "init":
@@ -287,11 +356,11 @@ export class RscRenderer {
       this.#logger.verbose(`init complete in ${Date.now() - startedAt}ms`);
       this.#send({ type: "ready" });
     } catch (error) {
-      this.#logger.error(`init failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+      const payload = this.#logRenderError("init failed", error, { requestId: "__init__", scope: "rsc-init" });
       this.#send({
         type: "error",
+        ...payload,
         requestId: "__init__",
-        message: error instanceof Error ? error.message : String(error),
       });
     }
   }
@@ -326,14 +395,15 @@ export class RscRenderer {
       this.#logger.verbose(`reload complete buildId=${msg.buildId} in ${Date.now() - startedAt}ms`);
       this.#send({ type: "reloaded", buildId: msg.buildId });
     } catch (error) {
-      this.#logger.error(
-        `reload failed buildId=${msg.buildId}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`,
-      );
+      const payload = this.#logRenderError(`reload failed buildId=${msg.buildId}`, error, {
+        requestId: "__reload__",
+        scope: "rsc-reload",
+      });
       this.#send({
         type: "error",
+        ...payload,
         requestId: "__reload__",
         buildId: msg.buildId,
-        message: error instanceof Error ? error.message : String(error),
       });
     }
   }
@@ -738,9 +808,13 @@ export class RscRenderer {
         this.#send({ type: "not-found", requestId });
         return;
       }
-      this.#logger.error(
-        `render[${requestId}] failed url=${url}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`,
-      );
+      const payload = this.#logRenderError("[RSC] worker render failed", error, {
+        requestId,
+        scope: "rsc-render",
+        url,
+        pathname: activeRoute.url?.pathname,
+        routeId: activeRoute.match?.pathRoute.path,
+      });
       const fallbackUrl = activeRoute.url;
       const fallbackMatch = activeRoute.match;
       if (
@@ -762,8 +836,8 @@ export class RscRenderer {
       }
       this.#send({
         type: "error",
+        ...payload,
         requestId,
-        message: error instanceof Error ? error.message : String(error),
       });
     } finally {
       this.#activeRenderReaders.delete(requestId);
@@ -834,6 +908,7 @@ export class RscRenderer {
     const controlRef: { current: RenderControl | null } = { current: null };
     const stream = await renderToReadableStream(element, clientManifest, {
       onError: (error) => {
+        if (controlRef.current?.type === "error") return controlRef.current.digest;
         if (isAkanRedirectError(error)) {
           controlRef.current = {
             type: "redirect",
@@ -851,8 +926,13 @@ export class RscRenderer {
           controlRef.current = { type: "not-found" };
           return error.digest;
         }
-        controlRef.current = { type: "error", error };
-        return error instanceof Error ? error.message : String(error);
+        const payload = this.#logRenderError("[RSC] worker render stream error", error, {
+          requestId: options.requestId,
+          scope: "rsc-stream",
+          trace: options.trace,
+        });
+        controlRef.current = { type: "error", error, errorId: payload.errorId, digest: payload.digest };
+        return payload.digest;
       },
     });
     const reader = stream.getReader();
@@ -991,11 +1071,14 @@ export class RscRenderer {
       this.#stats.totalFlightChunks += result.chunksCount;
       return true;
     } catch (fallbackError) {
-      this.#logger.error(
-        `render[${requestId}] custom ${kind} fallback failed: ${
-          fallbackError instanceof Error ? (fallbackError.stack ?? fallbackError.message) : String(fallbackError)
-        }`,
-      );
+      this.#logRenderError(`render[${requestId}] custom ${kind} fallback failed`, fallbackError, {
+        requestId,
+        scope: `fallback:${kind}`,
+        url,
+        pathname,
+        routeId: route.path,
+        trace,
+      });
       return false;
     }
   }
@@ -1025,11 +1108,13 @@ export class RscRenderer {
       this.#stats.totalFlightChunks += result.chunksCount;
       return true;
     } catch (error) {
-      this.#logger.error(
-        `render[${requestId}] system not-found fallback failed: ${
-          error instanceof Error ? (error.stack ?? error.message) : String(error)
-        }`,
-      );
+      this.#logRenderError(`render[${requestId}] system not-found fallback failed`, error, {
+        requestId,
+        scope: "fallback:system-not-found",
+        url,
+        pathname: url.pathname,
+        trace,
+      });
       return false;
     }
   }
@@ -1047,9 +1132,13 @@ export class RscRenderer {
       return;
     }
     if (control.type === "error") {
-      const message = control.error instanceof Error ? control.error.message : String(control.error);
-      this.#logger.verbose(`render[${requestId}] error`);
-      this.#send({ type: "error", requestId, message });
+      const payload = this.#createRenderErrorPayload(control.error, {
+        requestId,
+        scope: "rsc-render-control",
+        errorId: control.errorId,
+      });
+      this.#logger.verbose(`render[${requestId}] error errorId=${payload.errorId}`);
+      this.#send({ type: "error", ...payload, requestId });
       return;
     }
     this.#logger.verbose(`render[${requestId}] not-found`);

package/server/rscWorkerHost.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { type AkanI18nConfig, DEFAULT_AKAN_I18N, Logger } from "akanjs/common";
+import { type AkanI18nConfig, DEFAULT_AKAN_I18N, Logger, type LoggerMeta } from "akanjs/common";
 import type { AkanTheme } from "akanjs/fetch";
 import type { AkanMetricsReport } from "akanjs/service";
 import type { ClientManifest } from "./artifact";
@@ -14,7 +14,7 @@ const DEFAULT_RSC_HOST_MAX_PENDING_CHUNKS = 256;
 export interface RscPending {
   onChunk: (data: Uint8Array) => void;
   onEnd: () => void;
-  onError: (message: string) => void;
+  onError: (error: string | RscWorkerErrorPayload) => void;
   onMeta?: (meta: { theme?: AkanTheme; status?: number; trace?: RscTraceMetadata }) => void;
   onCacheState?: (state: RouteCacheRenderState) => void;
   onRedirect?: (location: string, method: RscRedirectMethod, status: RscRedirectStatus) => void;
@@ -25,6 +25,19 @@ export interface RscPending {
 export type RscRedirectMethod = "replace" | "push";
 export type RscRedirectStatus = 303 | 307 | 308;
 
+export interface RscWorkerErrorPayload {
+  message: string;
+  name?: string;
+  stack?: string;
+  errorId?: string;
+  digest?: string;
+  requestId?: string;
+  scope?: string;
+  pathname?: string;
+  routeId?: string;
+  meta?: LoggerMeta;
+}
+
 export interface RscWorkerInvalidateCacheMessage {
   type: "invalidate-cache";
   reason?: string;
@@ -35,6 +48,7 @@ export interface RscWorkerInvalidateCacheMessage {
 export type RscRenderResult =
   | {
       type: "stream";
+      requestId?: string;
       stream: ReadableStream<Uint8Array>;
       theme?: AkanTheme;
       status?: number;
@@ -66,6 +80,23 @@ function createRscRenderAbortError(reason?: unknown): Error {
   return error;
 }
 
+export function createRscWorkerError(input: string | RscWorkerErrorPayload): Error {
+  if (typeof input === "string") return new Error(input);
+  const error = new Error(input.message);
+  if (input.name) error.name = input.name;
+  if (input.stack) error.stack = input.stack;
+  Object.assign(error, {
+    errorId: input.errorId,
+    digest: input.digest ?? input.errorId,
+    requestId: input.requestId,
+    scope: input.scope,
+    pathname: input.pathname,
+    routeId: input.routeId,
+    meta: input.meta,
+  });
+  return error;
+}
+
 export function createIdempotentRscRenderCancel(onCancel: (reason?: unknown) => void): (reason?: unknown) => void {
   let cancelled = false;
   return (reason?: unknown) => {
@@ -89,6 +120,7 @@ export function createRscWorkerInvalidateCacheMessage(
 }
 
 export function createRscHostRenderStream(input: {
+  requestId?: string;
   setPending: (pending: RscPending) => void;
   deletePending: () => void;
   sendRenderOrQueue: () => void;
@@ -153,7 +185,17 @@ export function createRscHostRenderStream(input: {
         const settleStream = () => {
           if (settled) return;
           settled = true;
-          resolve({ type: "stream", stream, theme, status, trace, lateControl, cacheState, cancel: cancelRender });
+            resolve({
+              type: "stream",
+              requestId: input.requestId,
+              stream,
+              theme,
+              status,
+              trace,
+              lateControl,
+              cacheState,
+              cancel: cancelRender,
+            });
         };
         input.setPending({
           onMeta: (meta) => {
@@ -182,16 +224,17 @@ export function createRscHostRenderStream(input: {
             settleStream();
             controller.close();
           },
-          onError: (msg) => {
+          onError: (payload) => {
+            const error = createRscWorkerError(payload);
             settleLateControl(null);
             settleCacheState({ cacheable: false, reason: "error" });
             cleanupAbortListener();
             if (!settled) {
               settled = true;
-              reject(new Error(msg));
+              reject(error);
               return;
             }
-            controller.error(new Error(msg));
+            controller.error(error);
           },
           onRedirect: (location, method, status) => {
             settleLateControl(null);
@@ -262,7 +305,7 @@ type RscInMsg =
     }
   | { type: "not-found"; requestId: string }
   | { type: "metrics"; metrics: AkanMetricsReport }
-  | { type: "error"; requestId: string; message: string; buildId?: number };
+  | ({ type: "error"; requestId: string; buildId?: number } & RscWorkerErrorPayload);
 
 export interface RscWorkerReloadInput {
   clientManifest: ClientManifest;
@@ -379,7 +422,7 @@ export class RscWorker {
         this.#pending.set(requestId, {
           onChunk: (data) => controller.enqueue(data),
           onEnd: () => controller.close(),
-          onError: (msg) => controller.error(new Error(msg)),
+          onError: (payload) => controller.error(createRscWorkerError(payload)),
         });
         const send = () => {
 
@@ -412,6 +455,7 @@ export class RscWorker {
   ): Promise<RscRenderResult> {
     const requestId = crypto.randomUUID();
     return createRscHostRenderStream({
+      requestId,
       setPending: (pending) => {
         this.#pending.set(requestId, pending);
       },
@@ -656,8 +700,8 @@ export class RscWorker {
       case "error":
         if (message.requestId === "__init__") {
 
-          if (!this.#readyResolved) this.#rejectReady(new Error(String(message.message)));
-          else this.#logger.error(`[rsc] worker init error on restart: ${message.message}`);
+          if (!this.#readyResolved) this.#rejectReady(createRscWorkerError(message));
+          else this.#logger.errorObject("[rsc] worker init error on restart", createRscWorkerError(message), message.meta);
           return;
         }
         if (message.requestId === "__reload__") {
@@ -665,12 +709,12 @@ export class RscWorker {
             this.#pendingReload &&
             (message.buildId === undefined || this.#pendingReload.targetBuildId === message.buildId)
           ) {
-            this.#pendingReload.reject(new Error(String(message.message)));
+            this.#pendingReload.reject(createRscWorkerError(message));
             this.#pendingReload = null;
           }
           return;
         }
-        this.#resolvePending(message.requestId, (p) => p.onError(String(message.message)));
+        this.#resolvePending(message.requestId, (p) => p.onError(message));
         return;
     }
   }

package/server/ssrFromRscRenderer.tsx

@@ -595,11 +595,28 @@ export class SsrFromRscRenderer {
       : SsrFromRscRenderer.#clientBootstrap;
 
     const renderHtml = async () => {
-      const root = await thenable;
-      const stream = await renderToReadableStream(root, {
-        bootstrapScriptContent: bootstrap,
-      });
-      await stream.allReady;
+      let root: ReactNode;
+      try {
+        root = await thenable;
+      } catch (error) {
+        input.onError?.({ scope: "flight-decode", error });
+        throw error;
+      }
+      let stream: ReadableStream<Uint8Array> & { allReady: Promise<void> };
+      try {
+        stream = await renderToReadableStream(root, {
+          bootstrapScriptContent: bootstrap,
+        });
+      } catch (error) {
+        input.onError?.({ scope: "html-render", error });
+        throw error;
+      }
+      try {
+        await stream.allReady;
+      } catch (error) {
+        input.onError?.({ scope: "html-all-ready", error });
+        throw error;
+      }
       return stream;
     };
     const requestContext = input.requestStore ?? input.request;

package/server/ssrTypes.ts

@@ -73,4 +73,5 @@ export interface SsrFromRscInput {
   injectThemeInitScript?: boolean;
   lateControl?: Promise<SsrLateRedirect | null>;
   onCancel?: (reason?: unknown) => void;
+  onError?: (event: { scope: "flight-decode" | "html-render" | "html-all-ready"; error: unknown }) => void;
 }

package/server/webRouter.ts

@@ -6,6 +6,7 @@ import {
   DEFAULT_AKAN_I18N,
   getBasePathFromPathname,
   Logger,
+  type LoggerMeta,
   parseAkanI18nEnv,
 } from "akanjs/common";
 import { type AkanRequestStore, createRequestStore, parseCookieHeader } from "akanjs/fetch";
@@ -57,6 +58,15 @@ const RESERVED_BASE_PATHS = new Set(["admin"]);
 const CLIENT_CLOSED_REQUEST_STATUS = 499;
 export const DEFAULT_HTML_RESULT_CACHE_MAX_BODY_BYTES = 2 * 1024 * 1024;
 
+interface SsrErrorLogMeta extends LoggerMeta {
+  errorId: string;
+  requestId?: string;
+  scope: string;
+  pathname?: string;
+  routeId?: string;
+  url?: string;
+}
+
 export function createRscRedirectResponse(
   location: string,
   method: RscRedirectMethod,
@@ -449,10 +459,16 @@ export class WebRouter {
             return createRscRedirectResponse(result.location, result.method, result.status);
           if (result.type === "not-found") return WebRouter.#rscNotFoundResponse();
           if (result.status && result.status >= 500)
-            return this.#renderRscErrorResponse("__rsc", "Internal Server Error");
+            return this.#renderRscErrorResponse(
+              "__rsc",
+              new Error("RSC render returned an error status"),
+              req,
+              result.trace,
+              result.requestId,
+            );
           return createRscNavigationStreamResponse(result);
         } catch (err) {
-          return this.#renderRscErrorResponse("__rsc", err);
+          return this.#renderRscErrorResponse("__rsc", err, req);
         }
       },
       "/__rsc/manifest": () =>
@@ -530,6 +546,8 @@ export class WebRouter {
           );
         }
 
+        let activeRscRequestId: string | undefined;
+        let activeRscTrace: RscTraceMetadata | undefined;
         try {
           this.#requestStats.fullSsr += 1;
           const manifest = await this.#ensureRoute(url);
@@ -548,6 +566,10 @@ export class WebRouter {
             clientManifest: manifest.clientManifest,
             signal: req.signal,
           });
+          if (rscResult.type === "stream") {
+            activeRscRequestId = rscResult.requestId ?? rscResult.trace?.navId;
+            activeRscTrace = rscResult.trace;
+          }
           if (rscResult.type === "redirect")
             return Response.redirect(new URL(rscResult.location, url.origin), rscResult.status);
           if (rscResult.type === "not-found") return this.#renderSystemNotFoundFallbackResponse(req, url);
@@ -574,6 +596,22 @@ export class WebRouter {
             onCancel: (reason: unknown) => {
               rscResult.cancel(reason);
             },
+            onError: ({ scope, error }) => {
+              const meta = WebRouter.#createSsrErrorLogMeta(error, {
+                scope,
+                requestId: rscResult.requestId ?? rscResult.trace?.navId,
+                pathname: url.pathname,
+                routeId: rscResult.trace?.routeId,
+                url: url.href,
+              });
+              this.#logger.errorObject(
+                `[SSR] ${scope} failed requestId=${meta.requestId ?? "(none)"} pathname=${
+                  meta.pathname ?? "(unknown)"
+                } route=${meta.routeId ?? "(unknown)"} errorId=${meta.errorId}`,
+                error,
+                meta,
+              );
+            },
           });
           const responseStatus = rscResult.status ?? 200;
           const responseHeaders = WebRouter.#htmlResponseHeaders(responseStatus);
@@ -642,7 +680,11 @@ export class WebRouter {
             headers,
           });
         } catch (err) {
-          return this.#renderErrorResponse(req, url.pathname, err);
+          return this.#renderErrorResponse(req, "html", err, {
+            requestId: activeRscRequestId,
+            routeId: activeRscTrace?.routeId,
+            pathname: activeRscTrace?.pathname ?? url.pathname,
+          });
         }
       },
     };
@@ -797,34 +839,110 @@ export class WebRouter {
     });
   }
 
-  #renderErrorResponse(req: Request, scope: string, err: unknown): Promise<Response> {
+  #renderErrorResponse(
+    req: Request,
+    scope: string,
+    err: unknown,
+    input: { requestId?: string; pathname?: string; routeId?: string } = {},
+  ): Promise<Response> {
     if (WebRouter.#isExpectedRequestAbort(err)) return Promise.resolve(WebRouter.#clientClosedResponse());
     const message = err instanceof Error ? err.message : String(err);
-    this.#logger.error(`[SSR] render failed scope=${scope}: ${message}`);
+    const url = new URL(req.url);
+    const meta = WebRouter.#createSsrErrorLogMeta(err, {
+      scope,
+      requestId: input.requestId,
+      pathname: input.pathname ?? url.pathname,
+      routeId: input.routeId,
+      url: url.href,
+    });
+    this.#logger.errorObject(
+      `[SSR] render failed requestId=${meta.requestId ?? "(none)"} scope=${meta.scope} pathname=${
+        meta.pathname ?? "(unknown)"
+      } route=${meta.routeId ?? "(unknown)"} errorId=${meta.errorId}`,
+      err,
+      meta,
+    );
     this.#hub?.broadcast({ type: "error", message });
     return createSystemPageResponse({
       kind: "error",
       method: req.method,
-      pathname: scope,
-      lang: WebRouter.#getLocale(new URL(req.url).pathname, this.#artifact.i18n),
-      homeHref: this.#getSystemPageHomeHref(req, new URL(req.url).pathname),
-      stylesheetHref: this.#getStylesheetHref(req, new URL(req.url).pathname),
+      pathname: url.pathname,
+      lang: WebRouter.#getLocale(url.pathname, this.#artifact.i18n),
+      homeHref: this.#getSystemPageHomeHref(req, url.pathname),
+      stylesheetHref: this.#getStylesheetHref(req, url.pathname),
       showDetails: !this.#prodMode,
       error: err,
+    }).then((response) => {
+      response.headers.set("X-Akan-Error-Id", meta.errorId);
+      if (meta.requestId) response.headers.set("X-Akan-Rsc-Nav-Id", meta.requestId);
+      return response;
     });
   }
 
-  #renderRscErrorResponse(scope: string, err: unknown): Response {
+  #renderRscErrorResponse(
+    scope: string,
+    err: unknown,
+    req?: Request,
+    trace?: RscTraceMetadata,
+    requestId?: string,
+  ): Response {
     if (WebRouter.#isExpectedRequestAbort(err)) return WebRouter.#clientClosedResponse();
     const message = err instanceof Error ? err.message : String(err);
-    this.#logger.error(`[SSR] render failed scope=${scope}: ${message}`);
+    const url = req ? new URL(req.url) : undefined;
+    const meta = WebRouter.#createSsrErrorLogMeta(err, {
+      scope,
+      pathname: trace?.pathname ?? url?.pathname,
+      routeId: trace?.routeId,
+      requestId: trace?.navId ?? requestId,
+      url: url?.href,
+    });
+    this.#logger.errorObject(
+      `[SSR] render failed requestId=${meta.requestId ?? "(none)"} scope=${meta.scope} pathname=${
+        meta.pathname ?? "(unknown)"
+      } route=${meta.routeId ?? "(unknown)"} errorId=${meta.errorId}`,
+      err,
+      meta,
+    );
     this.#hub?.broadcast({ type: "error", message });
     return new Response("Internal Server Error", {
       status: 500,
-      headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" },
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        "Cache-Control": "no-store",
+        "X-Akan-Error-Id": meta.errorId,
+        ...(meta.requestId ? { "X-Akan-Rsc-Nav-Id": meta.requestId } : {}),
+      },
     });
   }
 
+  static #createSsrErrorLogMeta(
+    error: unknown,
+    input: { scope: string; requestId?: string; pathname?: string; routeId?: string; url?: string },
+  ): SsrErrorLogMeta {
+    const requestId = WebRouter.#stringErrorProp(error, "requestId") ?? input.requestId;
+    const scope = WebRouter.#stringErrorProp(error, "scope") ?? input.scope;
+    const pathname = WebRouter.#stringErrorProp(error, "pathname") ?? input.pathname;
+    const routeId = WebRouter.#stringErrorProp(error, "routeId") ?? input.routeId;
+    const errorId =
+      WebRouter.#stringErrorProp(error, "errorId") ??
+      WebRouter.#stringErrorProp(error, "digest") ??
+      Logger.createErrorId({ requestId, scope });
+    return {
+      errorId,
+      requestId,
+      scope,
+      pathname,
+      routeId,
+      url: input.url,
+    };
+  }
+
+  static #stringErrorProp(error: unknown, key: string): string | undefined {
+    if (typeof error !== "object" || error === null || !(key in error)) return undefined;
+    const value = (error as Record<string, unknown>)[key];
+    return typeof value === "string" && value ? value : undefined;
+  }
+
   static #clientClosedResponse(): Response {
     return new Response(null, {
       status: CLIENT_CLOSED_REQUEST_STATUS,

package/types/common/Logger.d.ts

@@ -1,10 +1,21 @@
 declare const logLevels: readonly ["trace", "verbose", "debug", "log", "info", "warn", "error"];
 export type LogLevel = (typeof logLevels)[number];
+export type LoggerMeta = Record<string, unknown>;
+export interface LoggerSerializedError {
+    name?: string;
+    message: string;
+    stack?: string;
+    cause?: LoggerSerializedError | string;
+    digest?: string;
+    code?: string | number;
+    status?: number;
+}
 export interface LoggerSinkEntry {
     stream: "stdout" | "stderr";
     level?: LogLevel;
     message: string;
     plainMessage: string;
+    meta?: LoggerMeta;
 }
 export type LoggerSink = (entry: LoggerSinkEntry) => void | Promise<void>;
 /** Log-level aware logger used by Akan runtime, CLI, and application services. */
@@ -26,6 +37,7 @@ export declare class Logger {
     info(msg: string, context?: string, name?: string): void;
     warn(msg: string, context?: string, name?: string): void;
     error(msg: string, context?: string, name?: string): void;
+    errorObject(msg: string, error: unknown, meta?: LoggerMeta, context?: string, name?: string): void;
     raw(msg: string, method?: "console" | "process"): void;
     rawLog(msg: string, method?: "console" | "process"): void;
     static trace(msg: string, context?: string, name?: string): void;
@@ -35,6 +47,14 @@ export declare class Logger {
     static info(msg: string, context?: string, name?: string): void;
     static warn(msg: string, context?: string, name?: string): void;
     static error(msg: string, context?: string, name?: string): void;
+    static errorObject(msg: string, error: unknown, meta?: LoggerMeta, context?: string, name?: string): void;
+    static createErrorId(input?: {
+        requestId?: string;
+        scope?: string;
+        sequence?: string | number;
+    }): string;
+    static serializeError(error: unknown): LoggerSerializedError;
+    static formatError(error: unknown): string;
     static rawLog(msg?: string, method?: "console" | "process", outputStream?: "log" | "error"): void;
     static raw(msg?: string, method?: "console" | "process", outputStream?: "log" | "error"): void;
 }

package/types/common/index.d.ts

@@ -13,7 +13,7 @@ export { isPhoneNumber } from "./isPhoneNumber.d.ts";
 export { isQueryEqual } from "./isQueryEqual.d.ts";
 export { isValidDate } from "./isValidDate.d.ts";
 export { decodeJwtPayload } from "./jwtDecode.d.ts";
-export { Logger, type LoggerSink, type LoggerSinkEntry, type LogLevel } from "./Logger.d.ts";
+export { Logger, type LoggerMeta, type LoggerSerializedError, type LoggerSink, type LoggerSinkEntry, type LogLevel, } from "./Logger.d.ts";
 export { type AkanI18nConfig, type AkanI18nConfigInput, DEFAULT_AKAN_I18N, parseAkanI18nEnv, resolveAkanI18nConfig, } from "./localeConfig.d.ts";
 export { lowerlize } from "./lowerlize.d.ts";
 export { mergeVersion } from "./mergeVersion.d.ts";

package/types/server/rscWorkerHost.d.ts

@@ -1,4 +1,4 @@
-import { type AkanI18nConfig } from "akanjs/common";
+import { type AkanI18nConfig, type LoggerMeta } from "akanjs/common";
 import type { AkanTheme } from "akanjs/fetch";
 import type { AkanMetricsReport } from "akanjs/service";
 import type { ClientManifest } from "./artifact.d.ts";
@@ -8,7 +8,7 @@ import type { BaseBuildArtifact, CssAsset } from "./types.d.ts";
 export interface RscPending {
     onChunk: (data: Uint8Array) => void;
     onEnd: () => void;
-    onError: (message: string) => void;
+    onError: (error: string | RscWorkerErrorPayload) => void;
     onMeta?: (meta: {
         theme?: AkanTheme;
         status?: number;
@@ -21,6 +21,18 @@ export interface RscPending {
 }
 export type RscRedirectMethod = "replace" | "push";
 export type RscRedirectStatus = 303 | 307 | 308;
+export interface RscWorkerErrorPayload {
+    message: string;
+    name?: string;
+    stack?: string;
+    errorId?: string;
+    digest?: string;
+    requestId?: string;
+    scope?: string;
+    pathname?: string;
+    routeId?: string;
+    meta?: LoggerMeta;
+}
 export interface RscWorkerInvalidateCacheMessage {
     type: "invalidate-cache";
     reason?: string;
@@ -29,6 +41,7 @@ export interface RscWorkerInvalidateCacheMessage {
 }
 export type RscRenderResult = {
     type: "stream";
+    requestId?: string;
     stream: ReadableStream<Uint8Array>;
     theme?: AkanTheme;
     status?: number;
@@ -47,9 +60,11 @@ export type RscRenderResult = {
 export declare function getRscHostMaxPendingChunks(value?: string | undefined): number;
 export declare function nextRscHostPendingChunkCount(currentPendingChunks: number, desiredSize: number | null): number;
 export declare function isRscHostPendingChunkOverflow(pendingChunks: number, maxPendingChunks: number): boolean;
+export declare function createRscWorkerError(input: string | RscWorkerErrorPayload): Error;
 export declare function createIdempotentRscRenderCancel(onCancel: (reason?: unknown) => void): (reason?: unknown) => void;
 export declare function createRscWorkerInvalidateCacheMessage(invalidation?: string | RouteCacheInvalidation): RscWorkerInvalidateCacheMessage;
 export declare function createRscHostRenderStream(input: {
+    requestId?: string;
     setPending: (pending: RscPending) => void;
     deletePending: () => void;
     sendRenderOrQueue: () => void;

package/types/server/ssrTypes.d.ts

@@ -70,4 +70,8 @@ export interface SsrFromRscInput {
     injectThemeInitScript?: boolean;
     lateControl?: Promise<SsrLateRedirect | null>;
     onCancel?: (reason?: unknown) => void;
+    onError?: (event: {
+        scope: "flight-decode" | "html-render" | "html-all-ready";
+        error: unknown;
+    }) => void;
 }