feat(core): Improve error formatting in ZodErrors integration

packages/core/package.json

@@ -61,5 +61,8 @@
  "volta": {
  "extends": "../../package.json"
  },
- "sideEffects": false
+ "sideEffects": false,
+ "devDependencies": {
+ "zod": "^3.24.1"
+ }
 }

packages/core/src/integrations/zoderrors.ts

@@ -5,33 +5,45 @@ import { truncate } from '../utils-hoist/string';
 
 interface ZodErrorsOptions {
  key?: string;
+ /**
+ * Limits the number of Zod errors inlined in each Sentry event.
+ *
+ * @default 10
+ */
  limit?: number;
+ /**
+ * Save full list of Zod issues as an attachment in Sentry
+ *
+ * @default false
+ */
+ saveZodIssuesAsAttachment?: boolean;
 }
 
 const DEFAULT_LIMIT = 10;
 const INTEGRATION_NAME = 'ZodErrors';
 
-// Simplified ZodIssue type definition
+/**
+ * Simplified ZodIssue type definition
+ */
 interface ZodIssue {
  path: (string | number)[];
  message?: string;
- expected?: string | number;
- received?: string | number;
+ expected?: unknown;
+ received?: unknown;
  unionErrors?: unknown[];
  keys?: unknown[];
+ invalid_literal?: unknown;
 }
 
 interface ZodError extends Error {
  issues: ZodIssue[];
-
- get errors(): ZodError['issues'];
 }
 
 function originalExceptionIsZodError(originalException: unknown): originalException is ZodError {
  return (
  isError(originalException) &&
  originalException.name === 'ZodError' &&
- Array.isArray((originalException as ZodError).errors)
+ Array.isArray((originalException as ZodError).issues)
  );
 }
 
@@ -45,9 +57,18 @@ type SingleLevelZodIssue<T extends ZodIssue> = {
 
 /**
  * Formats child objects or arrays to a string
- * That is preserved when sent to Sentry
+ * that is preserved when sent to Sentry.
+ *
+ * Without this, we end up with something like this in Sentry:
+ *
+ * [
+ * [Object],
+ * [Object],
+ * [Object],
+ * [Object]
+ * ]
  */
-function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
+export function flattenIssue(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  return {
  ...issue,
  path: 'path' in issue && Array.isArray(issue.path) ? issue.path.join('.') : undefined,
@@ -56,64 +77,145 @@ function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  };
 }
 
+/**
+ * Takes ZodError issue path array and returns a flattened version as a string.
+ * This makes it easier to display paths within a Sentry error message.
+ *
+ * Array indexes are normalized to reduce duplicate entries
+ *
+ * @param path ZodError issue path
+ * @returns flattened path
+ *
+ * @example
+ * flattenIssuePath([0, 'foo', 1, 'bar']) // -> '<array>.foo.<array>.bar'
+ */
+export function flattenIssuePath(path: Array<string | number>): string {
+ return path
+ .map(p => {
+ if (typeof p === 'number') {
+ return '<array>';
+ } else {
+ return p;
+ }
+ })
+ .join('.');
+}
+
 /**
  * Zod error message is a stringified version of ZodError.issues
  * This doesn't display well in the Sentry UI. Replace it with something shorter.
  */
-function formatIssueMessage(zodError: ZodError): string {
+export function formatIssueMessage(zodError: ZodError): string {
  const errorKeyMap = new Set<string | number | symbol>();
  for (const iss of zodError.issues) {
- if (iss.path?.[0]) {
- errorKeyMap.add(iss.path[0]);
+ const issuePath = flattenIssuePath(iss.path);
+ if (issuePath.length > 0) {
+ errorKeyMap.add(issuePath);
  }
  }
- const errorKeys = Array.from(errorKeyMap);
 
+ const errorKeys = Array.from(errorKeyMap);
+ if (errorKeys.length === 0) {
+ // If there are no keys, then we're likely validating the root
+ // variable rather than a key within an object. This attempts
+ // to extract what type it was that failed to validate.
+ // For example, z.string().parse(123) would return "string" here.
+ let rootExpectedType = 'variable';
+ if (zodError.issues.length > 0) {
+ const iss = zodError.issues[0];
+ if (iss !== undefined && 'expected' in iss && typeof iss.expected === 'string') {
+ rootExpectedType = iss.expected;
+ }
+ }
+ return `Failed to validate ${rootExpectedType}`;
+ }
  return `Failed to validate keys: ${truncate(errorKeys.join(', '), 100)}`;
 }
 
 /**
- * Applies ZodError issues to an event extras and replaces the error message
+ * Applies ZodError issues to an event extra and replaces the error message
  */
-export function applyZodErrorsToEvent(limit: number, event: Event, hint?: EventHint): Event {
+export function applyZodErrorsToEvent(
+ limit: number,
+ saveZodIssuesAsAttachment: boolean = false,
+ event: Event,
+ hint: EventHint,
+): Event {
  if (
  !event.exception?.values ||
- !hint?.originalException ||
+ !hint.originalException ||
  !originalExceptionIsZodError(hint.originalException) ||
  hint.originalException.issues.length === 0
  ) {
  return event;
  }
 
- return {
- ...event,
- exception: {
- ...event.exception,
- values: [
- {
- ...event.exception.values[0],
- value: formatIssueMessage(hint.originalException),
+ try {
+ const issuesToFlatten = saveZodIssuesAsAttachment
+ ? hint.originalException.issues
+ : hint.originalException.issues.slice(0, limit);
+ const flattenedIssues = issuesToFlatten.map(flattenIssue);
+
+ if (saveZodIssuesAsAttachment) {
+ // Sometimes having the full error details can be helpful.
+ // Attachments have much higher limits, so we can include the full list of issues.
+ if (!Array.isArray(hint.attachments)) {
+ hint.attachments = [];
+ }
+ hint.attachments.push({
+ filename: 'zod_issues.json',
+ data: JSON.stringify({
+ issues: flattenedIssues,
+ }),
+ });
+ }
+
+ return {
+ ...event,
+ exception: {
+ ...event.exception,
+ values: [
+ {
+ ...event.exception.values[0],
+ value: formatIssueMessage(hint.originalException),
+ },
+ ...event.exception.values.slice(1),
+ ],
+ },
+ extra: {
+ ...event.extra,
+ 'zoderror.issues': flattenedIssues.slice(0, limit),
+ },
+ };
+ } catch (e) {
+ // Hopefully we never throw errors here, but record it
+ // with the event just in case.
+ return {
+ ...event,
+ extra: {
+ ...event.extra,
+ 'zoderrors sentry integration parse error': {
+ message: 'an exception was thrown while processing ZodError within applyZodErrorsToEvent()',
+ error: e instanceof Error ? `${e.name}: ${e.message}\n${e.stack}` : 'unknown',
  },
- ...event.exception.values.slice(1),
- ],
- },
- extra: {
- ...event.extra,
- 'zoderror.issues': hint.originalException.errors.slice(0, limit).map(formatIssueTitle),
- },
- };
+ },
+ };
+ }
 }
 
 const _zodErrorsIntegration = ((options: ZodErrorsOptions = {}) => {
- const limit = options.limit || DEFAULT_LIMIT;
+ const limit = options.limit ?? DEFAULT_LIMIT;
 
  return {
  name: INTEGRATION_NAME,
- processEvent(originalEvent, hint) {
- const processedEvent = applyZodErrorsToEvent(limit, originalEvent, hint);
+ processEvent(originalEvent, hint): Event {
+ const processedEvent = applyZodErrorsToEvent(limit, options.saveZodIssuesAsAttachment, originalEvent, hint);
  return processedEvent;
  },
  };
 }) satisfies IntegrationFn;
 
+/**
+ * Sentry integration to process Zod errors, making them easier to work with in Sentry.
+ */
 export const zodErrorsIntegration = defineIntegration(_zodErrorsIntegration);

packages/core/package.json

@@ -61,5 +61,8 @@
  "volta": {
  "extends": "../../package.json"
  },
- "sideEffects": false
+ "sideEffects": false,
+ "devDependencies": {
+ "zod": "^3.24.1"
+ }
 }

packages/core/src/integrations/zoderrors.ts

@@ -5,33 +5,45 @@ import { truncate } from '../utils-hoist/string';
 
 interface ZodErrorsOptions {
  key?: string;
+ /**
+ * Limits the number of Zod errors inlined in each Sentry event.
+ *
+ * @default 10
+ */
  limit?: number;
+ /**
+ * Save full list of Zod issues as an attachment in Sentry
+ *
+ * @default false
+ */
+ saveZodIssuesAsAttachment?: boolean;
 }
 
 const DEFAULT_LIMIT = 10;
 const INTEGRATION_NAME = 'ZodErrors';
 
-// Simplified ZodIssue type definition
+/**
+ * Simplified ZodIssue type definition
+ */
 interface ZodIssue {
  path: (string | number)[];
  message?: string;
- expected?: string | number;
- received?: string | number;
+ expected?: unknown;
+ received?: unknown;
  unionErrors?: unknown[];
  keys?: unknown[];
+ invalid_literal?: unknown;
 }
 
 interface ZodError extends Error {
  issues: ZodIssue[];
-
- get errors(): ZodError['issues'];
 }
 
 function originalExceptionIsZodError(originalException: unknown): originalException is ZodError {
  return (
  isError(originalException) &&
  originalException.name === 'ZodError' &&
- Array.isArray((originalException as ZodError).errors)
+ Array.isArray((originalException as ZodError).issues)
  );
 }
 
@@ -45,9 +57,18 @@ type SingleLevelZodIssue<T extends ZodIssue> = {
 
 /**
  * Formats child objects or arrays to a string
- * That is preserved when sent to Sentry
+ * that is preserved when sent to Sentry.
+ *
+ * Without this, we end up with something like this in Sentry:
+ *
+ * [
+ * [Object],
+ * [Object],
+ * [Object],
+ * [Object]
+ * ]
  */
-function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
+export function flattenIssue(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  return {
  ...issue,
  path: 'path' in issue && Array.isArray(issue.path) ? issue.path.join('.') : undefined,
@@ -56,64 +77,145 @@ function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  };
 }
 
+/**
+ * Takes ZodError issue path array and returns a flattened version as a string.
+ * This makes it easier to display paths within a Sentry error message.
+ *
+ * Array indexes are normalized to reduce duplicate entries
+ *
+ * @param path ZodError issue path
+ * @returns flattened path
+ *
+ * @example
+ * flattenIssuePath([0, 'foo', 1, 'bar']) // -> '<array>.foo.<array>.bar'
+ */
+export function flattenIssuePath(path: Array<string | number>): string {
+ return path
+ .map(p => {
+ if (typeof p === 'number') {
+ return '<array>';
+ } else {
+ return p;
+ }
+ })
+ .join('.');
+}
+
 /**
  * Zod error message is a stringified version of ZodError.issues
  * This doesn't display well in the Sentry UI. Replace it with something shorter.
  */
-function formatIssueMessage(zodError: ZodError): string {
+export function formatIssueMessage(zodError: ZodError): string {
  const errorKeyMap = new Set<string | number | symbol>();
  for (const iss of zodError.issues) {
- if (iss.path?.[0]) {
- errorKeyMap.add(iss.path[0]);
+ const issuePath = flattenIssuePath(iss.path);
+ if (issuePath.length > 0) {
+ errorKeyMap.add(issuePath);
  }
  }
- const errorKeys = Array.from(errorKeyMap);
 
+ const errorKeys = Array.from(errorKeyMap);
+ if (errorKeys.length === 0) {
+ // If there are no keys, then we're likely validating the root
+ // variable rather than a key within an object. This attempts
+ // to extract what type it was that failed to validate.
+ // For example, z.string().parse(123) would return "string" here.
+ let rootExpectedType = 'variable';
+ if (zodError.issues.length > 0) {
+ const iss = zodError.issues[0];
+ if (iss !== undefined && 'expected' in iss && typeof iss.expected === 'string') {
+ rootExpectedType = iss.expected;
+ }
+ }
+ return `Failed to validate ${rootExpectedType}`;
+ }
  return `Failed to validate keys: ${truncate(errorKeys.join(', '), 100)}`;
 }
 
 /**
- * Applies ZodError issues to an event extras and replaces the error message
+ * Applies ZodError issues to an event extra and replaces the error message
  */
-export function applyZodErrorsToEvent(limit: number, event: Event, hint?: EventHint): Event {
+export function applyZodErrorsToEvent(
+ limit: number,
+ saveZodIssuesAsAttachment: boolean = false,
+ event: Event,
+ hint: EventHint,
+): Event {
  if (
  !event.exception?.values ||
- !hint?.originalException ||
+ !hint.originalException ||
  !originalExceptionIsZodError(hint.originalException) ||
  hint.originalException.issues.length === 0
  ) {
  return event;
  }
 
- return {
- ...event,
- exception: {
- ...event.exception,
- values: [
- {
- ...event.exception.values[0],
- value: formatIssueMessage(hint.originalException),
+ try {
+ const issuesToFlatten = saveZodIssuesAsAttachment
+ ? hint.originalException.issues
+ : hint.originalException.issues.slice(0, limit);
+ const flattenedIssues = issuesToFlatten.map(flattenIssue);
+
+ if (saveZodIssuesAsAttachment) {
+ // Sometimes having the full error details can be helpful.
+ // Attachments have much higher limits, so we can include the full list of issues.
+ if (!Array.isArray(hint.attachments)) {
+ hint.attachments = [];
+ }
+ hint.attachments.push({
+ filename: 'zod_issues.json',
+ data: JSON.stringify({
+ issues: flattenedIssues,
+ }),
+ });
+ }
+
+ return {
+ ...event,
+ exception: {
+ ...event.exception,
+ values: [
+ {
+ ...event.exception.values[0],
+ value: formatIssueMessage(hint.originalException),
+ },
+ ...event.exception.values.slice(1),
+ ],
+ },
+ extra: {
+ ...event.extra,
+ 'zoderror.issues': flattenedIssues.slice(0, limit),
+ },
+ };
+ } catch (e) {
+ // Hopefully we never throw errors here, but record it
+ // with the event just in case.
+ return {
+ ...event,
+ extra: {
+ ...event.extra,
+ 'zoderrors sentry integration parse error': {
+ message: 'an exception was thrown while processing ZodError within applyZodErrorsToEvent()',
+ error: e instanceof Error ? `${e.name}: ${e.message}\n${e.stack}` : 'unknown',
  },
- ...event.exception.values.slice(1),
- ],
- },
- extra: {
- ...event.extra,
- 'zoderror.issues': hint.originalException.errors.slice(0, limit).map(formatIssueTitle),
- },
- };
+ },
+ };
+ }
 }
 
 const _zodErrorsIntegration = ((options: ZodErrorsOptions = {}) => {
- const limit = options.limit || DEFAULT_LIMIT;
+ const limit = options.limit ?? DEFAULT_LIMIT;
 
  return {
  name: INTEGRATION_NAME,
- processEvent(originalEvent, hint) {
- const processedEvent = applyZodErrorsToEvent(limit, originalEvent, hint);
+ processEvent(originalEvent, hint): Event {
+ const processedEvent = applyZodErrorsToEvent(limit, options.saveZodIssuesAsAttachment, originalEvent, hint);
  return processedEvent;
  },
  };
 }) satisfies IntegrationFn;
 
+/**
+ * Sentry integration to process Zod errors, making them easier to work with in Sentry.
+ */
 export const zodErrorsIntegration = defineIntegration(_zodErrorsIntegration);

packages/core/package.json

@@ -61,5 +61,8 @@
  "volta": {
  "extends": "../../package.json"
  },
- "sideEffects": false
+ "sideEffects": false,
+ "devDependencies": {
+ "zod": "^3.24.1"
+ }
 }

packages/core/src/integrations/zoderrors.ts

@@ -5,33 +5,45 @@ import { truncate } from '../utils-hoist/string';
 
 interface ZodErrorsOptions {
  key?: string;
+ /**
+ * Limits the number of Zod errors inlined in each Sentry event.
+ *
+ * @default 10
+ */
  limit?: number;
+ /**
+ * Save full list of Zod issues as an attachment in Sentry
+ *
+ * @default false
+ */
+ saveZodIssuesAsAttachment?: boolean;
 }
 
 const DEFAULT_LIMIT = 10;
 const INTEGRATION_NAME = 'ZodErrors';
 
-// Simplified ZodIssue type definition
+/**
+ * Simplified ZodIssue type definition
+ */
 interface ZodIssue {
  path: (string | number)[];
  message?: string;
- expected?: string | number;
- received?: string | number;
+ expected?: unknown;
+ received?: unknown;
  unionErrors?: unknown[];
  keys?: unknown[];
+ invalid_literal?: unknown;
 }
 
 interface ZodError extends Error {
  issues: ZodIssue[];
-
- get errors(): ZodError['issues'];
 }
 
 function originalExceptionIsZodError(originalException: unknown): originalException is ZodError {
  return (
  isError(originalException) &&
  originalException.name === 'ZodError' &&
- Array.isArray((originalException as ZodError).errors)
+ Array.isArray((originalException as ZodError).issues)
  );
 }
 
@@ -45,9 +57,18 @@ type SingleLevelZodIssue<T extends ZodIssue> = {
 
 /**
  * Formats child objects or arrays to a string
- * That is preserved when sent to Sentry
+ * that is preserved when sent to Sentry.
+ *
+ * Without this, we end up with something like this in Sentry:
+ *
+ * [
+ * [Object],
+ * [Object],
+ * [Object],
+ * [Object]
+ * ]
  */
-function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
+export function flattenIssue(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  return {
  ...issue,
  path: 'path' in issue && Array.isArray(issue.path) ? issue.path.join('.') : undefined,
@@ -56,64 +77,145 @@ function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  };
 }
 
+/**
+ * Takes ZodError issue path array and returns a flattened version as a string.
+ * This makes it easier to display paths within a Sentry error message.
+ *
+ * Array indexes are normalized to reduce duplicate entries
+ *
+ * @param path ZodError issue path
+ * @returns flattened path
+ *
+ * @example
+ * flattenIssuePath([0, 'foo', 1, 'bar']) // -> '<array>.foo.<array>.bar'
+ */
+export function flattenIssuePath(path: Array<string | number>): string {
+ return path
+ .map(p => {
+ if (typeof p === 'number') {
+ return '<array>';
+ } else {
+ return p;
+ }
+ })
+ .join('.');
+}
+
 /**
  * Zod error message is a stringified version of ZodError.issues
  * This doesn't display well in the Sentry UI. Replace it with something shorter.
  */
-function formatIssueMessage(zodError: ZodError): string {
+export function formatIssueMessage(zodError: ZodError): string {
  const errorKeyMap = new Set<string | number | symbol>();
  for (const iss of zodError.issues) {
- if (iss.path?.[0]) {
- errorKeyMap.add(iss.path[0]);
+ const issuePath = flattenIssuePath(iss.path);
+ if (issuePath.length > 0) {
+ errorKeyMap.add(issuePath);
  }
  }
- const errorKeys = Array.from(errorKeyMap);
 
+ const errorKeys = Array.from(errorKeyMap);
+ if (errorKeys.length === 0) {
+ // If there are no keys, then we're likely validating the root
+ // variable rather than a key within an object. This attempts
+ // to extract what type it was that failed to validate.
+ // For example, z.string().parse(123) would return "string" here.
+ let rootExpectedType = 'variable';
+ if (zodError.issues.length > 0) {
+ const iss = zodError.issues[0];
+ if (iss !== undefined && 'expected' in iss && typeof iss.expected === 'string') {
+ rootExpectedType = iss.expected;
+ }
+ }
+ return `Failed to validate ${rootExpectedType}`;
+ }
  return `Failed to validate keys: ${truncate(errorKeys.join(', '), 100)}`;
 }
 
 /**
- * Applies ZodError issues to an event extras and replaces the error message
+ * Applies ZodError issues to an event extra and replaces the error message
  */
-export function applyZodErrorsToEvent(limit: number, event: Event, hint?: EventHint): Event {
+export function applyZodErrorsToEvent(
+ limit: number,
+ saveZodIssuesAsAttachment: boolean = false,
+ event: Event,
+ hint: EventHint,
+): Event {
  if (
  !event.exception?.values ||
- !hint?.originalException ||
+ !hint.originalException ||
  !originalExceptionIsZodError(hint.originalException) ||
  hint.originalException.issues.length === 0
  ) {
  return event;
  }
 
- return {
- ...event,
- exception: {
- ...event.exception,
- values: [
- {
- ...event.exception.values[0],
- value: formatIssueMessage(hint.originalException),
+ try {
+ const issuesToFlatten = saveZodIssuesAsAttachment
+ ? hint.originalException.issues
+ : hint.originalException.issues.slice(0, limit);
+ const flattenedIssues = issuesToFlatten.map(flattenIssue);
+
+ if (saveZodIssuesAsAttachment) {
+ // Sometimes having the full error details can be helpful.
+ // Attachments have much higher limits, so we can include the full list of issues.
+ if (!Array.isArray(hint.attachments)) {
+ hint.attachments = [];
+ }
+ hint.attachments.push({
+ filename: 'zod_issues.json',
+ data: JSON.stringify({
+ issues: flattenedIssues,
+ }),
+ });
+ }
+
+ return {
+ ...event,
+ exception: {
+ ...event.exception,
+ values: [
+ {
+ ...event.exception.values[0],
+ value: formatIssueMessage(hint.originalException),
+ },
+ ...event.exception.values.slice(1),
+ ],
+ },
+ extra: {
+ ...event.extra,
+ 'zoderror.issues': flattenedIssues.slice(0, limit),
+ },
+ };
+ } catch (e) {
+ // Hopefully we never throw errors here, but record it
+ // with the event just in case.
+ return {
+ ...event,
+ extra: {
+ ...event.extra,
+ 'zoderrors sentry integration parse error': {
+ message: 'an exception was thrown while processing ZodError within applyZodErrorsToEvent()',
+ error: e instanceof Error ? `${e.name}: ${e.message}\n${e.stack}` : 'unknown',
  },
- ...event.exception.values.slice(1),
- ],
- },
- extra: {
- ...event.extra,
- 'zoderror.issues': hint.originalException.errors.slice(0, limit).map(formatIssueTitle),
- },
- };
+ },
+ };
+ }
 }
 
 const _zodErrorsIntegration = ((options: ZodErrorsOptions = {}) => {
- const limit = options.limit || DEFAULT_LIMIT;
+ const limit = options.limit ?? DEFAULT_LIMIT;
 
  return {
  name: INTEGRATION_NAME,
- processEvent(originalEvent, hint) {
- const processedEvent = applyZodErrorsToEvent(limit, originalEvent, hint);
+ processEvent(originalEvent, hint): Event {
+ const processedEvent = applyZodErrorsToEvent(limit, options.saveZodIssuesAsAttachment, originalEvent, hint);
  return processedEvent;
  },
  };
 }) satisfies IntegrationFn;
 
+/**
+ * Sentry integration to process Zod errors, making them easier to work with in Sentry.
+ */
 export const zodErrorsIntegration = defineIntegration(_zodErrorsIntegration);

packages/core/package.json

@@ -61,5 +61,8 @@
  "volta": {
  "extends": "../../package.json"
  },
- "sideEffects": false
+ "sideEffects": false,
+ "devDependencies": {
+ "zod": "^3.24.1"
+ }
 }

packages/core/src/integrations/zoderrors.ts

@@ -5,33 +5,45 @@ import { truncate } from '../utils-hoist/string';
 
 interface ZodErrorsOptions {
  key?: string;
+ /**
+ * Limits the number of Zod errors inlined in each Sentry event.
+ *
+ * @default 10
+ */
  limit?: number;
+ /**
+ * Save full list of Zod issues as an attachment in Sentry
+ *
+ * @default false
+ */
+ saveZodIssuesAsAttachment?: boolean;
 }
 
 const DEFAULT_LIMIT = 10;
 const INTEGRATION_NAME = 'ZodErrors';
 
-// Simplified ZodIssue type definition
+/**
+ * Simplified ZodIssue type definition
+ */
 interface ZodIssue {
  path: (string | number)[];
  message?: string;
- expected?: string | number;
- received?: string | number;
+ expected?: unknown;
+ received?: unknown;
  unionErrors?: unknown[];
  keys?: unknown[];
+ invalid_literal?: unknown;
 }
 
 interface ZodError extends Error {
  issues: ZodIssue[];
-
- get errors(): ZodError['issues'];
 }
 
 function originalExceptionIsZodError(originalException: unknown): originalException is ZodError {
  return (
  isError(originalException) &&
  originalException.name === 'ZodError' &&
- Array.isArray((originalException as ZodError).errors)
+ Array.isArray((originalException as ZodError).issues)
  );
 }
 
@@ -45,9 +57,18 @@ type SingleLevelZodIssue<T extends ZodIssue> = {
 
 /**
  * Formats child objects or arrays to a string
- * That is preserved when sent to Sentry
+ * that is preserved when sent to Sentry.
+ *
+ * Without this, we end up with something like this in Sentry:
+ *
+ * [
+ * [Object],
+ * [Object],
+ * [Object],
+ * [Object]
+ * ]
  */
-function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
+export function flattenIssue(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  return {
  ...issue,
  path: 'path' in issue && Array.isArray(issue.path) ? issue.path.join('.') : undefined,
@@ -56,64 +77,145 @@ function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  };
 }
 
+/**
+ * Takes ZodError issue path array and returns a flattened version as a string.
+ * This makes it easier to display paths within a Sentry error message.
+ *
+ * Array indexes are normalized to reduce duplicate entries
+ *
+ * @param path ZodError issue path
+ * @returns flattened path
+ *
+ * @example
+ * flattenIssuePath([0, 'foo', 1, 'bar']) // -> '<array>.foo.<array>.bar'
+ */
+export function flattenIssuePath(path: Array<string | number>): string {
+ return path
+ .map(p => {
+ if (typeof p === 'number') {
+ return '<array>';
+ } else {
+ return p;
+ }
+ })
+ .join('.');
+}
+
 /**
  * Zod error message is a stringified version of ZodError.issues
  * This doesn't display well in the Sentry UI. Replace it with something shorter.
  */
-function formatIssueMessage(zodError: ZodError): string {
+export function formatIssueMessage(zodError: ZodError): string {
  const errorKeyMap = new Set<string | number | symbol>();
  for (const iss of zodError.issues) {
- if (iss.path?.[0]) {
- errorKeyMap.add(iss.path[0]);
+ const issuePath = flattenIssuePath(iss.path);
+ if (issuePath.length > 0) {
+ errorKeyMap.add(issuePath);
  }
  }
- const errorKeys = Array.from(errorKeyMap);
 
+ const errorKeys = Array.from(errorKeyMap);
+ if (errorKeys.length === 0) {
+ // If there are no keys, then we're likely validating the root
+ // variable rather than a key within an object. This attempts
+ // to extract what type it was that failed to validate.
+ // For example, z.string().parse(123) would return "string" here.
+ let rootExpectedType = 'variable';
+ if (zodError.issues.length > 0) {
+ const iss = zodError.issues[0];
+ if (iss !== undefined && 'expected' in iss && typeof iss.expected === 'string') {
+ rootExpectedType = iss.expected;
+ }
+ }
+ return `Failed to validate ${rootExpectedType}`;
+ }
  return `Failed to validate keys: ${truncate(errorKeys.join(', '), 100)}`;
 }
 
 /**
- * Applies ZodError issues to an event extras and replaces the error message
+ * Applies ZodError issues to an event extra and replaces the error message
  */
-export function applyZodErrorsToEvent(limit: number, event: Event, hint?: EventHint): Event {
+export function applyZodErrorsToEvent(
+ limit: number,
+ saveZodIssuesAsAttachment: boolean = false,
+ event: Event,
+ hint: EventHint,
+): Event {
  if (
  !event.exception?.values ||
- !hint?.originalException ||
+ !hint.originalException ||
  !originalExceptionIsZodError(hint.originalException) ||
  hint.originalException.issues.length === 0
  ) {
  return event;
  }
 
- return {
- ...event,
- exception: {
- ...event.exception,
- values: [
- {
- ...event.exception.values[0],
- value: formatIssueMessage(hint.originalException),
+ try {
+ const issuesToFlatten = saveZodIssuesAsAttachment
+ ? hint.originalException.issues
+ : hint.originalException.issues.slice(0, limit);
+ const flattenedIssues = issuesToFlatten.map(flattenIssue);
+
+ if (saveZodIssuesAsAttachment) {
+ // Sometimes having the full error details can be helpful.
+ // Attachments have much higher limits, so we can include the full list of issues.
+ if (!Array.isArray(hint.attachments)) {
+ hint.attachments = [];
+ }
+ hint.attachments.push({
+ filename: 'zod_issues.json',
+ data: JSON.stringify({
+ issues: flattenedIssues,
+ }),
+ });
+ }
+
+ return {
+ ...event,
+ exception: {
+ ...event.exception,
+ values: [
+ {
+ ...event.exception.values[0],
+ value: formatIssueMessage(hint.originalException),
+ },
+ ...event.exception.values.slice(1),
+ ],
+ },
+ extra: {
+ ...event.extra,
+ 'zoderror.issues': flattenedIssues.slice(0, limit),
+ },
+ };
+ } catch (e) {
+ // Hopefully we never throw errors here, but record it
+ // with the event just in case.
+ return {
+ ...event,
+ extra: {
+ ...event.extra,
+ 'zoderrors sentry integration parse error': {
+ message: 'an exception was thrown while processing ZodError within applyZodErrorsToEvent()',
+ error: e instanceof Error ? `${e.name}: ${e.message}\n${e.stack}` : 'unknown',
  },
- ...event.exception.values.slice(1),
- ],
- },
- extra: {
- ...event.extra,
- 'zoderror.issues': hint.originalException.errors.slice(0, limit).map(formatIssueTitle),
- },
- };
+ },
+ };
+ }
 }
 
 const _zodErrorsIntegration = ((options: ZodErrorsOptions = {}) => {
- const limit = options.limit || DEFAULT_LIMIT;
+ const limit = options.limit ?? DEFAULT_LIMIT;
 
  return {
  name: INTEGRATION_NAME,
- processEvent(originalEvent, hint) {
- const processedEvent = applyZodErrorsToEvent(limit, originalEvent, hint);
+ processEvent(originalEvent, hint): Event {
+ const processedEvent = applyZodErrorsToEvent(limit, options.saveZodIssuesAsAttachment, originalEvent, hint);
  return processedEvent;
  },
  };
 }) satisfies IntegrationFn;
 
+/**
+ * Sentry integration to process Zod errors, making them easier to work with in Sentry.
+ */
 export const zodErrorsIntegration = defineIntegration(_zodErrorsIntegration);

packages/core/package.json

@@ -61,5 +61,8 @@
  "volta": {
  "extends": "../../package.json"
  },
- "sideEffects": false
+ "sideEffects": false,
+ "devDependencies": {
+ "zod": "^3.24.1"
+ }
 }

packages/core/src/integrations/zoderrors.ts

@@ -5,33 +5,45 @@ import { truncate } from '../utils-hoist/string';
 
 interface ZodErrorsOptions {
  key?: string;
+ /**
+ * Limits the number of Zod errors inlined in each Sentry event.
+ *
+ * @default 10
+ */
  limit?: number;
+ /**
+ * Save full list of Zod issues as an attachment in Sentry
+ *
+ * @default false
+ */
+ saveZodIssuesAsAttachment?: boolean;
 }
 
 const DEFAULT_LIMIT = 10;
 const INTEGRATION_NAME = 'ZodErrors';
 
-// Simplified ZodIssue type definition
+/**
+ * Simplified ZodIssue type definition
+ */
 interface ZodIssue {
  path: (string | number)[];
  message?: string;
- expected?: string | number;
- received?: string | number;
+ expected?: unknown;
+ received?: unknown;
  unionErrors?: unknown[];
  keys?: unknown[];
+ invalid_literal?: unknown;
 }
 
 interface ZodError extends Error {
  issues: ZodIssue[];
-
- get errors(): ZodError['issues'];
 }
 
 function originalExceptionIsZodError(originalException: unknown): originalException is ZodError {
  return (
  isError(originalException) &&
  originalException.name === 'ZodError' &&
- Array.isArray((originalException as ZodError).errors)
+ Array.isArray((originalException as ZodError).issues)
  );
 }
 
@@ -45,9 +57,18 @@ type SingleLevelZodIssue<T extends ZodIssue> = {
 
 /**
  * Formats child objects or arrays to a string
- * That is preserved when sent to Sentry
+ * that is preserved when sent to Sentry.
+ *
+ * Without this, we end up with something like this in Sentry:
+ *
+ * [
+ * [Object],
+ * [Object],
+ * [Object],
+ * [Object]
+ * ]
  */
-function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
+export function flattenIssue(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  return {
  ...issue,
  path: 'path' in issue && Array.isArray(issue.path) ? issue.path.join('.') : undefined,
@@ -56,64 +77,145 @@ function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  };
 }
 
+/**
+ * Takes ZodError issue path array and returns a flattened version as a string.
+ * This makes it easier to display paths within a Sentry error message.
+ *
+ * Array indexes are normalized to reduce duplicate entries
+ *
+ * @param path ZodError issue path
+ * @returns flattened path
+ *
+ * @example
+ * flattenIssuePath([0, 'foo', 1, 'bar']) // -> '<array>.foo.<array>.bar'
+ */
+export function flattenIssuePath(path: Array<string | number>): string {
+ return path
+ .map(p => {
+ if (typeof p === 'number') {
+ return '<array>';
+ } else {
+ return p;
+ }
+ })
+ .join('.');
+}
+
 /**
  * Zod error message is a stringified version of ZodError.issues
  * This doesn't display well in the Sentry UI. Replace it with something shorter.
  */
-function formatIssueMessage(zodError: ZodError): string {
+export function formatIssueMessage(zodError: ZodError): string {
  const errorKeyMap = new Set<string | number | symbol>();
  for (const iss of zodError.issues) {
- if (iss.path?.[0]) {
- errorKeyMap.add(iss.path[0]);
+ const issuePath = flattenIssuePath(iss.path);
+ if (issuePath.length > 0) {
+ errorKeyMap.add(issuePath);
  }
  }
- const errorKeys = Array.from(errorKeyMap);
 
+ const errorKeys = Array.from(errorKeyMap);
+ if (errorKeys.length === 0) {
+ // If there are no keys, then we're likely validating the root
+ // variable rather than a key within an object. This attempts
+ // to extract what type it was that failed to validate.
+ // For example, z.string().parse(123) would return "string" here.
+ let rootExpectedType = 'variable';
+ if (zodError.issues.length > 0) {
+ const iss = zodError.issues[0];
+ if (iss !== undefined && 'expected' in iss && typeof iss.expected === 'string') {
+ rootExpectedType = iss.expected;
+ }
+ }
+ return `Failed to validate ${rootExpectedType}`;
+ }
  return `Failed to validate keys: ${truncate(errorKeys.join(', '), 100)}`;
 }
 
 /**
- * Applies ZodError issues to an event extras and replaces the error message
+ * Applies ZodError issues to an event extra and replaces the error message
  */
-export function applyZodErrorsToEvent(limit: number, event: Event, hint?: EventHint): Event {
+export function applyZodErrorsToEvent(
+ limit: number,
+ saveZodIssuesAsAttachment: boolean = false,
+ event: Event,
+ hint: EventHint,
+): Event {
  if (
  !event.exception?.values ||
- !hint?.originalException ||
+ !hint.originalException ||
  !originalExceptionIsZodError(hint.originalException) ||
  hint.originalException.issues.length === 0
  ) {
  return event;
  }
 
- return {
- ...event,
- exception: {
- ...event.exception,
- values: [
- {
- ...event.exception.values[0],
- value: formatIssueMessage(hint.originalException),
+ try {
+ const issuesToFlatten = saveZodIssuesAsAttachment
+ ? hint.originalException.issues
+ : hint.originalException.issues.slice(0, limit);
+ const flattenedIssues = issuesToFlatten.map(flattenIssue);
+
+ if (saveZodIssuesAsAttachment) {
+ // Sometimes having the full error details can be helpful.
+ // Attachments have much higher limits, so we can include the full list of issues.
+ if (!Array.isArray(hint.attachments)) {
+ hint.attachments = [];
+ }
+ hint.attachments.push({
+ filename: 'zod_issues.json',
+ data: JSON.stringify({
+ issues: flattenedIssues,
+ }),
+ });
+ }
+
+ return {
+ ...event,
+ exception: {
+ ...event.exception,
+ values: [
+ {
+ ...event.exception.values[0],
+ value: formatIssueMessage(hint.originalException),
+ },
+ ...event.exception.values.slice(1),
+ ],
+ },
+ extra: {
+ ...event.extra,
+ 'zoderror.issues': flattenedIssues.slice(0, limit),
+ },
+ };
+ } catch (e) {
+ // Hopefully we never throw errors here, but record it
+ // with the event just in case.
+ return {
+ ...event,
+ extra: {
+ ...event.extra,
+ 'zoderrors sentry integration parse error': {
+ message: 'an exception was thrown while processing ZodError within applyZodErrorsToEvent()',
+ error: e instanceof Error ? `${e.name}: ${e.message}\n${e.stack}` : 'unknown',
  },
- ...event.exception.values.slice(1),
- ],
- },
- extra: {
- ...event.extra,
- 'zoderror.issues': hint.originalException.errors.slice(0, limit).map(formatIssueTitle),
- },
- };
+ },
+ };
+ }
 }
 
 const _zodErrorsIntegration = ((options: ZodErrorsOptions = {}) => {
- const limit = options.limit || DEFAULT_LIMIT;
+ const limit = options.limit ?? DEFAULT_LIMIT;
 
  return {
  name: INTEGRATION_NAME,
- processEvent(originalEvent, hint) {
- const processedEvent = applyZodErrorsToEvent(limit, originalEvent, hint);
+ processEvent(originalEvent, hint): Event {
+ const processedEvent = applyZodErrorsToEvent(limit, options.saveZodIssuesAsAttachment, originalEvent, hint);
  return processedEvent;
  },
  };
 }) satisfies IntegrationFn;
 
+/**
+ * Sentry integration to process Zod errors, making them easier to work with in Sentry.
+ */
 export const zodErrorsIntegration = defineIntegration(_zodErrorsIntegration);

packages/core/package.json

@@ -61,5 +61,8 @@
  "volta": {
  "extends": "../../package.json"
  },
- "sideEffects": false
+ "sideEffects": false,
+ "devDependencies": {
+ "zod": "^3.24.1"
+ }
 }

packages/core/src/integrations/zoderrors.ts

@@ -5,33 +5,45 @@ import { truncate } from '../utils-hoist/string';
 
 interface ZodErrorsOptions {
  key?: string;
+ /**
+ * Limits the number of Zod errors inlined in each Sentry event.
+ *
+ * @default 10
+ */
  limit?: number;
+ /**
+ * Save full list of Zod issues as an attachment in Sentry
+ *
+ * @default false
+ */
+ saveZodIssuesAsAttachment?: boolean;
 }
 
 const DEFAULT_LIMIT = 10;
 const INTEGRATION_NAME = 'ZodErrors';
 
-// Simplified ZodIssue type definition
+/**
+ * Simplified ZodIssue type definition
+ */
 interface ZodIssue {
  path: (string | number)[];
  message?: string;
- expected?: string | number;
- received?: string | number;
+ expected?: unknown;
+ received?: unknown;
  unionErrors?: unknown[];
  keys?: unknown[];
+ invalid_literal?: unknown;
 }
 
 interface ZodError extends Error {
  issues: ZodIssue[];
-
- get errors(): ZodError['issues'];
 }
 
 function originalExceptionIsZodError(originalException: unknown): originalException is ZodError {
  return (
  isError(originalException) &&
  originalException.name === 'ZodError' &&
- Array.isArray((originalException as ZodError).errors)
+ Array.isArray((originalException as ZodError).issues)
  );
 }
 
@@ -45,9 +57,18 @@ type SingleLevelZodIssue<T extends ZodIssue> = {
 
 /**
  * Formats child objects or arrays to a string
- * That is preserved when sent to Sentry
+ * that is preserved when sent to Sentry.
+ *
+ * Without this, we end up with something like this in Sentry:
+ *
+ * [
+ * [Object],
+ * [Object],
+ * [Object],
+ * [Object]
+ * ]
  */
-function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
+export function flattenIssue(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  return {
  ...issue,
  path: 'path' in issue && Array.isArray(issue.path) ? issue.path.join('.') : undefined,
@@ -56,64 +77,145 @@ function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  };
 }
 
+/**
+ * Takes ZodError issue path array and returns a flattened version as a string.
+ * This makes it easier to display paths within a Sentry error message.
+ *
+ * Array indexes are normalized to reduce duplicate entries
+ *
+ * @param path ZodError issue path
+ * @returns flattened path
+ *
+ * @example
+ * flattenIssuePath([0, 'foo', 1, 'bar']) // -> '<array>.foo.<array>.bar'
+ */
+export function flattenIssuePath(path: Array<string | number>): string {
+ return path
+ .map(p => {
+ if (typeof p === 'number') {
+ return '<array>';
+ } else {
+ return p;
+ }
+ })
+ .join('.');
+}
+
 /**
  * Zod error message is a stringified version of ZodError.issues
  * This doesn't display well in the Sentry UI. Replace it with something shorter.
  */
-function formatIssueMessage(zodError: ZodError): string {
+export function formatIssueMessage(zodError: ZodError): string {
  const errorKeyMap = new Set<string | number | symbol>();
  for (const iss of zodError.issues) {
- if (iss.path?.[0]) {
- errorKeyMap.add(iss.path[0]);
+ const issuePath = flattenIssuePath(iss.path);
+ if (issuePath.length > 0) {
+ errorKeyMap.add(issuePath);
  }
  }
- const errorKeys = Array.from(errorKeyMap);
 
+ const errorKeys = Array.from(errorKeyMap);
+ if (errorKeys.length === 0) {
+ // If there are no keys, then we're likely validating the root
+ // variable rather than a key within an object. This attempts
+ // to extract what type it was that failed to validate.
+ // For example, z.string().parse(123) would return "string" here.
+ let rootExpectedType = 'variable';
+ if (zodError.issues.length > 0) {
+ const iss = zodError.issues[0];
+ if (iss !== undefined && 'expected' in iss && typeof iss.expected === 'string') {
+ rootExpectedType = iss.expected;
+ }
+ }
+ return `Failed to validate ${rootExpectedType}`;
+ }
  return `Failed to validate keys: ${truncate(errorKeys.join(', '), 100)}`;
 }
 
 /**
- * Applies ZodError issues to an event extras and replaces the error message
+ * Applies ZodError issues to an event extra and replaces the error message
  */
-export function applyZodErrorsToEvent(limit: number, event: Event, hint?: EventHint): Event {
+export function applyZodErrorsToEvent(
+ limit: number,
+ saveZodIssuesAsAttachment: boolean = false,
+ event: Event,
+ hint: EventHint,
+): Event {
  if (
  !event.exception?.values ||
- !hint?.originalException ||
+ !hint.originalException ||
  !originalExceptionIsZodError(hint.originalException) ||
  hint.originalException.issues.length === 0
  ) {
  return event;
  }
 
- return {
- ...event,
- exception: {
- ...event.exception,
- values: [
- {
- ...event.exception.values[0],
- value: formatIssueMessage(hint.originalException),
+ try {
+ const issuesToFlatten = saveZodIssuesAsAttachment
+ ? hint.originalException.issues
+ : hint.originalException.issues.slice(0, limit);
+ const flattenedIssues = issuesToFlatten.map(flattenIssue);
+
+ if (saveZodIssuesAsAttachment) {
+ // Sometimes having the full error details can be helpful.
+ // Attachments have much higher limits, so we can include the full list of issues.
+ if (!Array.isArray(hint.attachments)) {
+ hint.attachments = [];
+ }
+ hint.attachments.push({
+ filename: 'zod_issues.json',
+ data: JSON.stringify({
+ issues: flattenedIssues,
+ }),
+ });
+ }
+
+ return {
+ ...event,
+ exception: {
+ ...event.exception,
+ values: [
+ {
+ ...event.exception.values[0],
+ value: formatIssueMessage(hint.originalException),
+ },
+ ...event.exception.values.slice(1),
+ ],
+ },
+ extra: {
+ ...event.extra,
+ 'zoderror.issues': flattenedIssues.slice(0, limit),
+ },
+ };
+ } catch (e) {
+ // Hopefully we never throw errors here, but record it
+ // with the event just in case.
+ return {
+ ...event,
+ extra: {
+ ...event.extra,
+ 'zoderrors sentry integration parse error': {
+ message: 'an exception was thrown while processing ZodError within applyZodErrorsToEvent()',
+ error: e instanceof Error ? `${e.name}: ${e.message}\n${e.stack}` : 'unknown',
  },
- ...event.exception.values.slice(1),
- ],
- },
- extra: {
- ...event.extra,
- 'zoderror.issues': hint.originalException.errors.slice(0, limit).map(formatIssueTitle),
- },
- };
+ },
+ };
+ }
 }
 
 const _zodErrorsIntegration = ((options: ZodErrorsOptions = {}) => {
- const limit = options.limit || DEFAULT_LIMIT;
+ const limit = options.limit ?? DEFAULT_LIMIT;
 
  return {
  name: INTEGRATION_NAME,
- processEvent(originalEvent, hint) {
- const processedEvent = applyZodErrorsToEvent(limit, originalEvent, hint);
+ processEvent(originalEvent, hint): Event {
+ const processedEvent = applyZodErrorsToEvent(limit, options.saveZodIssuesAsAttachment, originalEvent, hint);
  return processedEvent;
  },
  };
 }) satisfies IntegrationFn;
 
+/**
+ * Sentry integration to process Zod errors, making them easier to work with in Sentry.
+ */
 export const zodErrorsIntegration = defineIntegration(_zodErrorsIntegration);

packages/core/package.json

@@ -61,5 +61,8 @@
  "volta": {
  "extends": "../../package.json"
  },
- "sideEffects": false
+ "sideEffects": false,
+ "devDependencies": {
+ "zod": "^3.24.1"
+ }
 }

packages/core/src/integrations/zoderrors.ts

@@ -5,33 +5,45 @@ import { truncate } from '../utils-hoist/string';
 
 interface ZodErrorsOptions {
  key?: string;
+ /**
+ * Limits the number of Zod errors inlined in each Sentry event.
+ *
+ * @default 10
+ */
  limit?: number;
+ /**
+ * Save full list of Zod issues as an attachment in Sentry
+ *
+ * @default false
+ */
+ saveZodIssuesAsAttachment?: boolean;
 }
 
 const DEFAULT_LIMIT = 10;
 const INTEGRATION_NAME = 'ZodErrors';
 
-// Simplified ZodIssue type definition
+/**
+ * Simplified ZodIssue type definition
+ */
 interface ZodIssue {
  path: (string | number)[];
  message?: string;
- expected?: string | number;
- received?: string | number;
+ expected?: unknown;
+ received?: unknown;
  unionErrors?: unknown[];
  keys?: unknown[];
+ invalid_literal?: unknown;
 }
 
 interface ZodError extends Error {
  issues: ZodIssue[];
-
- get errors(): ZodError['issues'];
 }
 
 function originalExceptionIsZodError(originalException: unknown): originalException is ZodError {
  return (
  isError(originalException) &&
  originalException.name === 'ZodError' &&
- Array.isArray((originalException as ZodError).errors)
+ Array.isArray((originalException as ZodError).issues)
  );
 }
 
@@ -45,9 +57,18 @@ type SingleLevelZodIssue<T extends ZodIssue> = {
 
 /**
  * Formats child objects or arrays to a string
- * That is preserved when sent to Sentry
+ * that is preserved when sent to Sentry.
+ *
+ * Without this, we end up with something like this in Sentry:
+ *
+ * [
+ * [Object],
+ * [Object],
+ * [Object],
+ * [Object]
+ * ]
  */
-function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
+export function flattenIssue(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  return {
  ...issue,
  path: 'path' in issue && Array.isArray(issue.path) ? issue.path.join('.') : undefined,
@@ -56,64 +77,145 @@ function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  };
 }
 
+/**
+ * Takes ZodError issue path array and returns a flattened version as a string.
+ * This makes it easier to display paths within a Sentry error message.
+ *
+ * Array indexes are normalized to reduce duplicate entries
+ *
+ * @param path ZodError issue path
+ * @returns flattened path
+ *
+ * @example
+ * flattenIssuePath([0, 'foo', 1, 'bar']) // -> '<array>.foo.<array>.bar'
+ */
+export function flattenIssuePath(path: Array<string | number>): string {
+ return path
+ .map(p => {
+ if (typeof p === 'number') {
+ return '<array>';
+ } else {
+ return p;
+ }
+ })
+ .join('.');
+}
+
 /**
  * Zod error message is a stringified version of ZodError.issues
  * This doesn't display well in the Sentry UI. Replace it with something shorter.
  */
-function formatIssueMessage(zodError: ZodError): string {
+export function formatIssueMessage(zodError: ZodError): string {
  const errorKeyMap = new Set<string | number | symbol>();
  for (const iss of zodError.issues) {
- if (iss.path?.[0]) {
- errorKeyMap.add(iss.path[0]);
+ const issuePath = flattenIssuePath(iss.path);
+ if (issuePath.length > 0) {
+ errorKeyMap.add(issuePath);
  }
  }
- const errorKeys = Array.from(errorKeyMap);
 
+ const errorKeys = Array.from(errorKeyMap);
+ if (errorKeys.length === 0) {
+ // If there are no keys, then we're likely validating the root
+ // variable rather than a key within an object. This attempts
+ // to extract what type it was that failed to validate.
+ // For example, z.string().parse(123) would return "string" here.
+ let rootExpectedType = 'variable';
+ if (zodError.issues.length > 0) {
+ const iss = zodError.issues[0];
+ if (iss !== undefined && 'expected' in iss && typeof iss.expected === 'string') {
+ rootExpectedType = iss.expected;
+ }
+ }
+ return `Failed to validate ${rootExpectedType}`;
+ }
  return `Failed to validate keys: ${truncate(errorKeys.join(', '), 100)}`;
 }
 
 /**
- * Applies ZodError issues to an event extras and replaces the error message
+ * Applies ZodError issues to an event extra and replaces the error message
  */
-export function applyZodErrorsToEvent(limit: number, event: Event, hint?: EventHint): Event {
+export function applyZodErrorsToEvent(
+ limit: number,
+ saveZodIssuesAsAttachment: boolean = false,
+ event: Event,
+ hint: EventHint,
+): Event {
  if (
  !event.exception?.values ||
- !hint?.originalException ||
+ !hint.originalException ||
  !originalExceptionIsZodError(hint.originalException) ||
  hint.originalException.issues.length === 0
  ) {
  return event;
  }
 
- return {
- ...event,
- exception: {
- ...event.exception,
- values: [
- {
- ...event.exception.values[0],
- value: formatIssueMessage(hint.originalException),
+ try {
+ const issuesToFlatten = saveZodIssuesAsAttachment
+ ? hint.originalException.issues
+ : hint.originalException.issues.slice(0, limit);
+ const flattenedIssues = issuesToFlatten.map(flattenIssue);
+
+ if (saveZodIssuesAsAttachment) {
+ // Sometimes having the full error details can be helpful.
+ // Attachments have much higher limits, so we can include the full list of issues.
+ if (!Array.isArray(hint.attachments)) {
+ hint.attachments = [];
+ }
+ hint.attachments.push({
+ filename: 'zod_issues.json',
+ data: JSON.stringify({
+ issues: flattenedIssues,
+ }),
+ });
+ }
+
+ return {
+ ...event,
+ exception: {
+ ...event.exception,
+ values: [
+ {
+ ...event.exception.values[0],
+ value: formatIssueMessage(hint.originalException),
+ },
+ ...event.exception.values.slice(1),
+ ],
+ },
+ extra: {
+ ...event.extra,
+ 'zoderror.issues': flattenedIssues.slice(0, limit),
+ },
+ };
+ } catch (e) {
+ // Hopefully we never throw errors here, but record it
+ // with the event just in case.
+ return {
+ ...event,
+ extra: {
+ ...event.extra,
+ 'zoderrors sentry integration parse error': {
+ message: 'an exception was thrown while processing ZodError within applyZodErrorsToEvent()',
+ error: e instanceof Error ? `${e.name}: ${e.message}\n${e.stack}` : 'unknown',
  },
- ...event.exception.values.slice(1),
- ],
- },
- extra: {
- ...event.extra,
- 'zoderror.issues': hint.originalException.errors.slice(0, limit).map(formatIssueTitle),
- },
- };
+ },
+ };
+ }
 }
 
 const _zodErrorsIntegration = ((options: ZodErrorsOptions = {}) => {
- const limit = options.limit || DEFAULT_LIMIT;
+ const limit = options.limit ?? DEFAULT_LIMIT;
 
  return {
  name: INTEGRATION_NAME,
- processEvent(originalEvent, hint) {
- const processedEvent = applyZodErrorsToEvent(limit, originalEvent, hint);
+ processEvent(originalEvent, hint): Event {
+ const processedEvent = applyZodErrorsToEvent(limit, options.saveZodIssuesAsAttachment, originalEvent, hint);
  return processedEvent;
  },
  };
 }) satisfies IntegrationFn;
 
+/**
+ * Sentry integration to process Zod errors, making them easier to work with in Sentry.
+ */
 export const zodErrorsIntegration = defineIntegration(_zodErrorsIntegration);

packages/core/package.json

@@ -61,5 +61,8 @@
  "volta": {
  "extends": "../../package.json"
  },
- "sideEffects": false
+ "sideEffects": false,
+ "devDependencies": {
+ "zod": "^3.24.1"
+ }
 }

packages/core/src/integrations/zoderrors.ts

@@ -5,33 +5,45 @@ import { truncate } from '../utils-hoist/string';
 
 interface ZodErrorsOptions {
  key?: string;
+ /**
+ * Limits the number of Zod errors inlined in each Sentry event.
+ *
+ * @default 10
+ */
  limit?: number;
+ /**
+ * Save full list of Zod issues as an attachment in Sentry
+ *
+ * @default false
+ */
+ saveZodIssuesAsAttachment?: boolean;
 }
 
 const DEFAULT_LIMIT = 10;
 const INTEGRATION_NAME = 'ZodErrors';
 
-// Simplified ZodIssue type definition
+/**
+ * Simplified ZodIssue type definition
+ */
 interface ZodIssue {
  path: (string | number)[];
  message?: string;
- expected?: string | number;
- received?: string | number;
+ expected?: unknown;
+ received?: unknown;
  unionErrors?: unknown[];
  keys?: unknown[];
+ invalid_literal?: unknown;
 }
 
 interface ZodError extends Error {
  issues: ZodIssue[];
-
- get errors(): ZodError['issues'];
 }
 
 function originalExceptionIsZodError(originalException: unknown): originalException is ZodError {
  return (
  isError(originalException) &&
  originalException.name === 'ZodError' &&
- Array.isArray((originalException as ZodError).errors)
+ Array.isArray((originalException as ZodError).issues)
  );
 }
 
@@ -45,9 +57,18 @@ type SingleLevelZodIssue<T extends ZodIssue> = {
 
 /**
  * Formats child objects or arrays to a string
- * That is preserved when sent to Sentry
+ * that is preserved when sent to Sentry.
+ *
+ * Without this, we end up with something like this in Sentry:
+ *
+ * [
+ * [Object],
+ * [Object],
+ * [Object],
+ * [Object]
+ * ]
  */
-function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
+export function flattenIssue(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  return {
  ...issue,
  path: 'path' in issue && Array.isArray(issue.path) ? issue.path.join('.') : undefined,
@@ -56,64 +77,145 @@ function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
  };
 }
 
+/**
+ * Takes ZodError issue path array and returns a flattened version as a string.
+ * This makes it easier to display paths within a Sentry error message.
+ *
+ * Array indexes are normalized to reduce duplicate entries
+ *
+ * @param path ZodError issue path
+ * @returns flattened path
+ *
+ * @example
+ * flattenIssuePath([0, 'foo', 1, 'bar']) // -> '<array>.foo.<array>.bar'
+ */
+export function flattenIssuePath(path: Array<string | number>): string {
+ return path
+ .map(p => {
+ if (typeof p === 'number') {
+ return '<array>';
+ } else {
+ return p;
+ }
+ })
+ .join('.');
+}
+
 /**
  * Zod error message is a stringified version of ZodError.issues
  * This doesn't display well in the Sentry UI. Replace it with something shorter.
  */
-function formatIssueMessage(zodError: ZodError): string {
+export function formatIssueMessage(zodError: ZodError): string {
  const errorKeyMap = new Set<string | number | symbol>();
  for (const iss of zodError.issues) {
- if (iss.path?.[0]) {
- errorKeyMap.add(iss.path[0]);
+ const issuePath = flattenIssuePath(iss.path);
+ if (issuePath.length > 0) {
+ errorKeyMap.add(issuePath);
  }
  }
- const errorKeys = Array.from(errorKeyMap);
 
+ const errorKeys = Array.from(errorKeyMap);
+ if (errorKeys.length === 0) {
+ // If there are no keys, then we're likely validating the root
+ // variable rather than a key within an object. This attempts
+ // to extract what type it was that failed to validate.
+ // For example, z.string().parse(123) would return "string" here.
+ let rootExpectedType = 'variable';
+ if (zodError.issues.length > 0) {
+ const iss = zodError.issues[0];
+ if (iss !== undefined && 'expected' in iss && typeof iss.expected === 'string') {
+ rootExpectedType = iss.expected;
+ }
+ }
+ return `Failed to validate ${rootExpectedType}`;
+ }
  return `Failed to validate keys: ${truncate(errorKeys.join(', '), 100)}`;
 }
 
 /**
- * Applies ZodError issues to an event extras and replaces the error message
+ * Applies ZodError issues to an event extra and replaces the error message
  */
-export function applyZodErrorsToEvent(limit: number, event: Event, hint?: EventHint): Event {
+export function applyZodErrorsToEvent(
+ limit: number,
+ saveZodIssuesAsAttachment: boolean = false,
+ event: Event,
+ hint: EventHint,
+): Event {
  if (
  !event.exception?.values ||
- !hint?.originalException ||
+ !hint.originalException ||
  !originalExceptionIsZodError(hint.originalException) ||
  hint.originalException.issues.length === 0
  ) {
  return event;
  }
 
- return {
- ...event,
- exception: {
- ...event.exception,
- values: [
- {
- ...event.exception.values[0],
- value: formatIssueMessage(hint.originalException),
+ try {
+ const issuesToFlatten = saveZodIssuesAsAttachment
+ ? hint.originalException.issues
+ : hint.originalException.issues.slice(0, limit);
+ const flattenedIssues = issuesToFlatten.map(flattenIssue);
+
+ if (saveZodIssuesAsAttachment) {
+ // Sometimes having the full error details can be helpful.
+ // Attachments have much higher limits, so we can include the full list of issues.
+ if (!Array.isArray(hint.attachments)) {
+ hint.attachments = [];
+ }
+ hint.attachments.push({
+ filename: 'zod_issues.json',
+ data: JSON.stringify({
+ issues: flattenedIssues,
+ }),
+ });
+ }
+
+ return {
+ ...event,
+ exception: {
+ ...event.exception,
+ values: [
+ {
+ ...event.exception.values[0],
+ value: formatIssueMessage(hint.originalException),
+ },
+ ...event.exception.values.slice(1),
+ ],
+ },
+ extra: {
+ ...event.extra,
+ 'zoderror.issues': flattenedIssues.slice(0, limit),
+ },
+ };
+ } catch (e) {
+ // Hopefully we never throw errors here, but record it
+ // with the event just in case.
+ return {
+ ...event,
+ extra: {
+ ...event.extra,
+ 'zoderrors sentry integration parse error': {
+ message: 'an exception was thrown while processing ZodError within applyZodErrorsToEvent()',
+ error: e instanceof Error ? `${e.name}: ${e.message}\n${e.stack}` : 'unknown',
  },
- ...event.exception.values.slice(1),
- ],
- },
- extra: {
- ...event.extra,
- 'zoderror.issues': hint.originalException.errors.slice(0, limit).map(formatIssueTitle),
- },
- };
+ },
+ };
+ }
 }
 
 const _zodErrorsIntegration = ((options: ZodErrorsOptions = {}) => {
- const limit = options.limit || DEFAULT_LIMIT;
+ const limit = options.limit ?? DEFAULT_LIMIT;
 
  return {
  name: INTEGRATION_NAME,
- processEvent(originalEvent, hint) {
- const processedEvent = applyZodErrorsToEvent(limit, originalEvent, hint);
+ processEvent(originalEvent, hint): Event {
+ const processedEvent = applyZodErrorsToEvent(limit, options.saveZodIssuesAsAttachment, originalEvent, hint);
  return processedEvent;
  },
  };
 }) satisfies IntegrationFn;
 
+/**
+ * Sentry integration to process Zod errors, making them easier to work with in Sentry.
+ */
 export const zodErrorsIntegration = defineIntegration(_zodErrorsIntegration);