Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Server api errors and unhandled errors should print stack trace in logs (#209)

Srajan Asthanaa3f662de4e75
diff --git a/packages/harness/src/request-reply/executor.ts b/packages/harness/src/request-reply/executor.ts
index ceeb3ab67..dbda98ee0 100644
--- a/packages/harness/src/request-reply/executor.ts
+++ b/packages/harness/src/request-reply/executor.ts
@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
import type { RedisClientType } from 'redis';
import type { Logger } from 'winston';
import z from 'zod';
+import { extractErrorLogFields } from '../core/util/errorLogFields';
import { ReplyError } from './errors';
import type { JSONReply, RequestHandler } from './types';
import { publishedRequestSchema } from './types';
@@ -104,7 +105,7 @@ export class RequestReplyExecutor {
this.subscriberClient.on('error', (err: Error) => {
this.logger.error('[RequestReplyExecutor] Subscriber error', {
executorId: this.executorId,
- error: err.message,
+ ...extractErrorLogFields(err),
});
this.onError?.(err, { executorId: this.executorId, channel: this.channel });
this.stopHeartbeat();
@@ -139,7 +140,7 @@ export class RequestReplyExecutor {
const error = err instanceof Error ? err : new Error(String(err), { cause: err });
this.logger.error('[RequestReplyExecutor] Error subscribing to request channel', {
executorId: this.executorId,
- error: error.message,
+ ...extractErrorLogFields(error),
});
this.onError?.(error, { executorId: this.executorId, channel: this.channel });
this.stopHeartbeat();
@@ -151,8 +152,10 @@ export class RequestReplyExecutor {
try {
await this.redis.set(this.heartbeatKey, '1', { PX: this.heartbeatTtlMs });
} catch (err) {
- const error = err instanceof Error ? err.message : String(err);
- this.logger.error('[RequestReplyExecutor] Heartbeat error', { executorId: this.executorId, error });
+ this.logger.error('[RequestReplyExecutor] Heartbeat error', {
+ executorId: this.executorId,
+ ...extractErrorLogFields(err),
+ });
}
}
@@ -186,7 +189,7 @@ export class RequestReplyExecutor {
// Drop the request, this should never happen
this.logger.warn('[RequestReplyExecutor] Request message is not valid JSON', { executorId: this.executorId });
this.onError?.(
- new Error(`Request message is not valid JSON for executorId: ${this.executorId}, message: ${message}`, {
+ new Error(`Request message is not valid JSON for executorId: ${this.executorId}`, {
cause: err,
}),
{
@@ -233,9 +236,9 @@ export class RequestReplyExecutor {
await this.redis.set(replyKey, JSON.stringify(replyPayload), { PX: this.replyTtlMs });
} catch (err) {
this.logger.error('[RequestReplyExecutor] Request processing failed', {
- error: err instanceof Error ? err.message : String(err),
executorId: this.executorId,
replyKey,
+ ...extractErrorLogFields(err),
});
}
}
diff --git a/packages/server/src/apis/auth.ts b/packages/server/src/apis/auth.ts
index 1edf85be5..d82857fb5 100644
--- a/packages/server/src/apis/auth.ts
+++ b/packages/server/src/apis/auth.ts
@@ -1,4 +1,5 @@
import { OpenAPIHono } from '@hono/zod-openapi';
+import { extractErrorLogFields } from '@truefoundry/utils-core/core';
import type { Configuration } from 'openid-client';
import type { Logger } from 'winston';
import { clearAuthCookie, ID_TOKEN_COOKIE, OAUTH_STATE_COOKIE, readOAuthStateCookie } from '../auth/cookies';
@@ -34,9 +35,7 @@ export function createAuthRouter(params: { oidcClient: Configuration | undefined
});
return c.redirect(authorizationUrl, 302);
} catch (error) {
- params.logger.error('Failed to build login authorization', {
- error: error instanceof Error ? error.message : error,
- });
+ params.logger.error('Failed to build login authorization', extractErrorLogFields(error));
return c.redirect(oauthErrorRedirect('login_failed'), 302);
}
});
@@ -69,9 +68,7 @@ export function createAuthRouter(params: { oidcClient: Configuration | undefined
});
return c.redirect(safeReturnTo(pending.return_to), 302);
} catch (error) {
- params.logger.error('Failed to exchange authorization code', {
- error: error instanceof Error ? error.message : error,
- });
+ params.logger.error('Failed to exchange authorization code', extractErrorLogFields(error));
const reason = error instanceof Error ? error.message : 'login_failed';
return c.redirect(oauthErrorRedirect(reason), 302);
}
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index ad1b19e8a..baf1d6981 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -2,8 +2,9 @@
import { swaggerUI } from '@hono/swagger-ui';
import { OpenAPIHono, z } from '@hono/zod-openapi';
import type { ISessionStore, Sessions, TurnStreamingEvent } from '@truefoundry/utils-core/agent-session';
+import { extractErrorLogFields } from '@truefoundry/utils-core/core';
import type { RequestReplyRouter } from '@truefoundry/utils-core/request-reply';
-import type { Context } from 'hono';
+import type { Context, ErrorHandler } from 'hono';
import { HTTPException } from 'hono/http-exception';
import type { Configuration } from 'openid-client';
import type { RedisClientType } from 'redis';
@@ -38,6 +39,25 @@ import { zodErrorResponse, zodValidationHook } from './zodErrorResponse';
const BEARER_AUTH_SCHEME = 'BearerAuth';
+export function createAppErrorHandler(params: { logger: Logger }): ErrorHandler {
+ return (error, c) => {
+ if (error instanceof z.ZodError) {
+ return zodErrorResponse(c, error);
+ }
+ if (error instanceof HTTPException) {
+ if (error.status >= 500) {
+ params.logger.error('Server API error', {
+ status: error.status,
+ ...extractErrorLogFields(error),
+ });
+ }
+ return c.json({ error: { message: error.message } }, error.status);
+ }
+ params.logger.error('Unhandled error', extractErrorLogFields(error));
+ return c.json({ error: { message: 'Internal server error' } }, 500);
+ };
+}
+
const openApiDocConfig = {
openapi: '3.1.0',
info: {
@@ -266,16 +286,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
app.notFound(routeNotFound);
- app.onError((error, c) => {
- if (error instanceof z.ZodError) {
- return zodErrorResponse(c, error);
- }
- if (error instanceof HTTPException) {
- return c.json({ error: { message: error.message } }, error.status);
- }
- deps.logger.error('Unhandled error', { message: error.message, stack: error.stack });
- return c.json({ error: { message: 'Internal server error' } }, 500);
- });
+ app.onError(createAppErrorHandler({ logger: deps.logger }));
return app;
}
diff --git a/packages/server/src/cli.ts b/packages/server/src/cli.ts
index c800a71dd..8e2ffe0ac 100644
--- a/packages/server/src/cli.ts
+++ b/packages/server/src/cli.ts
@@ -54,6 +54,6 @@ try {
await import('./main.js');
}
} catch (error) {
- console.error(error instanceof Error ? error.message : error);
+ console.error(error);
process.exit(1);
}
diff --git a/packages/server/src/db/postgres/session-store/queries/sessions.ts b/packages/server/src/db/postgres/session-store/queries/sessions.ts
index 8be21d754..3d2d15525 100644
--- a/packages/server/src/db/postgres/session-store/queries/sessions.ts
+++ b/packages/server/src/db/postgres/session-store/queries/sessions.ts
@@ -104,7 +104,7 @@ export async function createSession(db: Kysely<Database>, input: CreateSessionIn
.execute();
} catch (error) {
if (isPgUniqueViolation(error)) {
- throw new SessionAlreadyExistsError(input.session_id);
+ throw new SessionAlreadyExistsError(input.session_id, { cause: error });
}
throw error;
}
diff --git a/packages/server/src/db/postgres/session-store/queries/turns.ts b/packages/server/src/db/postgres/session-store/queries/turns.ts
index 7819f9e03..5eeb73526 100644
--- a/packages/server/src/db/postgres/session-store/queries/turns.ts
+++ b/packages/server/src/db/postgres/session-store/queries/turns.ts
@@ -579,7 +579,7 @@ export async function createTurn(db: Kysely<Database>, input: CreateTurnInput):
});
} catch (err) {
if (err instanceof SessionStoreNotFoundError || err instanceof SessionStoreConflictError) throw err;
- if (isUniqueViolation(err)) throw new TurnAlreadyExistsError(input.turn.turn_id);
+ if (isUniqueViolation(err)) throw new TurnAlreadyExistsError(input.turn.turn_id, { cause: err });
throw err;
}
}
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 49c5cda8a..2eaf02f9a 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -9,6 +9,7 @@
* (migrate, Redis, listen) are caught below and exit non-zero. SQLite vs
* Postgres store modules stay dynamic so only the active engine is loaded.
*/
+import { extractErrorLogFields } from '@truefoundry/utils-core/core';
import { mkdir } from 'node:fs/promises';
import path from 'node:path';
@@ -270,7 +271,7 @@ try {
if (redis) {
requestReplySubscriber = redis.duplicate();
requestReplySubscriber.on('error', (error: Error) => {
- logger.error('[RedisSubscriber] Client error', { error: error.message });
+ logger.error('[RedisSubscriber] Client error', extractErrorLogFields(error));
});
await requestReplySubscriber.connect();
requestReplyExecutor = new RequestReplyExecutor({
@@ -326,14 +327,10 @@ try {
// the clients this process owns: the subscriber duplicate and the primary.
await requestReplyExecutor?.drain();
await requestReplySubscriber?.close().catch((error: unknown) => {
- logger.warn('[Redis] Error closing subscriber client during shutdown', {
- error: error instanceof Error ? error.message : String(error),
- });
+ logger.warn('[Redis] Error closing subscriber client during shutdown', extractErrorLogFields(error));
});
await redis?.close().catch((error: unknown) => {
- logger.warn('[Redis] Error closing client during shutdown', {
- error: error instanceof Error ? error.message : String(error),
- });
+ logger.warn('[Redis] Error closing client during shutdown', extractErrorLogFields(error));
});
await destroyDb();
process.exit(0);
diff --git a/packages/server/src/mcp/auth/mcpDcr.ts b/packages/server/src/mcp/auth/mcpDcr.ts
index c98a61ceb..a69291340 100644
--- a/packages/server/src/mcp/auth/mcpDcr.ts
+++ b/packages/server/src/mcp/auth/mcpDcr.ts
@@ -223,7 +223,7 @@ export async function buildMcpAuthorizationUrl(params: {
});
} catch (error: unknown) {
throw new McpConnectionError(`Failed to start OAuth authorization for MCP server '${params.mcpServerName}'`, 424, {
- cause: error instanceof Error ? error : undefined,
+ cause: error,
});
}
await params.tokenStore.savePendingAuthorization({
diff --git a/packages/server/src/mcp/auth/mcpOAuthHelpers.ts b/packages/server/src/mcp/auth/mcpOAuthHelpers.ts
index 3b28cf627..84932b329 100644
--- a/packages/server/src/mcp/auth/mcpOAuthHelpers.ts
+++ b/packages/server/src/mcp/auth/mcpOAuthHelpers.ts
@@ -18,8 +18,10 @@ export function mcpOAuthCallbackUrl(): string {
try {
const publicBaseUrl = getPublicBaseUrl();
return `${publicBaseUrl}${MCP_OAUTH_CALLBACK_PATH}`;
- } catch {
- throw new McpConnectionError('PUBLIC_BASE_URL is required for MCP OAuth registration but was empty', 500);
+ } catch (error) {
+ throw new McpConnectionError('PUBLIC_BASE_URL is required for MCP OAuth registration but was empty', 500, {
+ cause: error,
+ });
}
}
@@ -80,8 +82,8 @@ export function validateRedirectUris({ redirectUris }: { redirectUris: string[]
let parsed: URL;
try {
parsed = new URL(redirectUri);
- } catch {
- throw new McpConnectionError(`Invalid redirect URI: ${redirectUri}. Must be a valid URL.`, 400);
+ } catch (error) {
+ throw new McpConnectionError(`Invalid redirect URI: ${redirectUri}. Must be a valid URL.`, 400, { cause: error });
}
if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
throw new McpConnectionError(`Invalid redirect URI: ${redirectUri}. Must be a valid URL.`, 400);
diff --git a/packages/server/src/runtime/redis.ts b/packages/server/src/runtime/redis.ts
index 1f214183b..8dbf95c06 100644
--- a/packages/server/src/runtime/redis.ts
+++ b/packages/server/src/runtime/redis.ts
@@ -3,6 +3,7 @@
* boot, closed last during shutdown. Injected into the request-reply
* transport (which duplicates it only for its subscriber).
*/
+import { extractErrorLogFields } from '@truefoundry/utils-core/core';
import { createClient, type RedisClientType } from 'redis';
import type { Logger } from 'winston';
@@ -11,7 +12,7 @@ export async function connectRedis(input: { url: string; logger: Logger }): Prom
// Without an 'error' listener node-redis crashes the process on emit;
// reconnects are automatic, so log and keep running.
client.on('error', (error: Error) => {
- input.logger.error('[Redis] Client error', { error: error.message });
+ input.logger.error('[Redis] Client error', extractErrorLogFields(error));
});
await client.connect();
return client;
diff --git a/packages/server/tests/unit/appErrorHandler.test.ts b/packages/server/tests/unit/appErrorHandler.test.ts
new file mode 100644
index 000000000..62184aa4c
--- /dev/null
+++ b/packages/server/tests/unit/appErrorHandler.test.ts
@@ -0,0 +1,61 @@
+import { OpenAPIHono } from '@hono/zod-openapi';
+import { HTTPException } from 'hono/http-exception';
+import winston from 'winston';
+import { createAppErrorHandler } from '../../src/app';
+
+describe('createAppErrorHandler', () => {
+ it('logs the stack for an unhandled error and returns a generic 500', async () => {
+ const logger = winston.createLogger({ silent: true });
+ const errorLog = jest.spyOn(logger, 'error');
+ const app = new OpenAPIHono();
+ const thrown = new Error('unexpected failure');
+ app.onError(createAppErrorHandler({ logger }));
+ app.get('/test', () => {
+ throw thrown;
+ });
+
+ const response = await app.request('/test');
+
+ expect(response.status).toBe(500);
+ expect(await response.json()).toEqual({ error: { message: 'Internal server error' } });
+ expect(errorLog).toHaveBeenCalledWith('Unhandled error', {
+ error: thrown.message,
+ stack: thrown.stack,
+ });
+ });
+
+ it('logs the stack and status for a server HTTP exception', async () => {
+ const logger = winston.createLogger({ silent: true });
+ const errorLog = jest.spyOn(logger, 'error');
+ const app = new OpenAPIHono();
+ const thrown = new HTTPException(503, { message: 'Service unavailable' });
+ app.onError(createAppErrorHandler({ logger }));
+ app.get('/test', () => {
+ throw thrown;
+ });
+
+ const response = await app.request('/test');
+
+ expect(response.status).toBe(503);
+ expect(errorLog).toHaveBeenCalledWith('Server API error', {
+ status: 503,
+ error: thrown.message,
+ stack: thrown.stack,
+ });
+ });
+
+ it('does not error-log a client HTTP exception', async () => {
+ const logger = winston.createLogger({ silent: true });
+ const errorLog = jest.spyOn(logger, 'error');
+ const app = new OpenAPIHono();
+ app.onError(createAppErrorHandler({ logger }));
+ app.get('/test', () => {
+ throw new HTTPException(404, { message: 'Not found' });
+ });
+
+ const response = await app.request('/test');
+
+ expect(response.status).toBe(404);
+ expect(errorLog).not.toHaveBeenCalled();
+ });
+});