PII detection failed: ${error instanceof Error ? error.stack

Error message

PII detection failed: ${error instanceof Error ? error.stack : 'Unknown error'}

What it means

PIIDetectorProcessor.processInput wraps all detection work in a try/catch; TripWire errors (an intentional detection trip) are re-thrown as-is, but any other failure is re-wrapped in this generic Error carrying the original stack. It signals the processor itself failed (not that PII was found).

Source

Thrown at packages/core/src/processors/processors/pii-detector.ts:346

          } else if (this.strategy === 'redact') {
            if (processedMessage) {
              processedMessages.push(processedMessage);
            } else {
              processedMessages.push(message); // Fallback to original if redaction failed
            }
            continue;
          }
        }

        processedMessages.push(message);
      }

      return processedMessages;
    } catch (error) {
      if (error instanceof TripWire) {
        throw error; // Re-throw tripwire errors
      }
      throw new Error(`PII detection failed: ${error instanceof Error ? error.stack : 'Unknown error'}`);
    }
  }

  /**
   * Notify the consumer-supplied `onDetection` callback. Never throws.
   */
  private async emitDetection(input: string, detectionResult: PIIDetectionResult, flagged: boolean): Promise<void> {
    if (!this.onDetection) return;
    try {
      await this.onDetection({
        detectionResult,
        input,
        flagged,
        strategyApplied: flagged ? this.strategy : 'none',
      });
    } catch (error) {
      console.warn('[PIIDetector] onDetection callback failed:', error);
    }

View on GitHub (pinned to 75dd419e61)

Solutions

Read the embedded stack in the message to find the root cause (it is the original error.stack)
Validate processor options (patterns, entity types) at construction
Verify any detection model/API configuration (keys, endpoints) if using model-based detection
If you need to distinguish intentional detections, catch TripWire separately before this generic error

Example fix

// before
new PIIDetectorProcessor({ patterns: { email: '(unclosed[') });
// after
new PIIDetectorProcessor({ patterns: { email: '[^@\\s]+@[^@\\s]+\\.[a-z]+' });

Defensive patterns

Strategy: try-catch

Validate before calling

const opts = { patterns: {...} };
for (const [name, re] of Object.entries(opts.patterns ?? {})) {
  new RegExp(re); // throws early on invalid patterns
}

Type guard

function isTripWire(e: unknown): e is TripWire {
  return e instanceof TripWire;
}
function isProcessorFailure(e: unknown): e is Error {
  return e instanceof Error && e.message.startsWith('PII detection failed');
}

Try / catch

try {
  processed = await processor.processInput(messages);
} catch (e) {
  if (isTripWire(e)) throw e;
  if (isProcessorFailure(e)) {
    logger.error('PII processor crashed', { stack: e.message });
    return messages; // fail-open, or rethrow for fail-closed
  }
  throw e;
}

Prevention

Validate regex patterns and processor options at construction time
Monitor detection model health/credentials if using model-based detection
Pin @mastra/core versions and review changelogs for message format changes
Decide and document fail-open vs fail-closed policy for detection outages

When it happens

Trigger: The underlying detection engine throws: malformed regex patterns, detector model/API errors when using model-based detection, bad options passed to the processor, or unexpected message shapes (e.g. non-string content where text is expected).

Common situations: Misconfigured PII entity types or regexes in processor options; network/auth failures from a detection model; upstream library version changes altering message formats; bugs in custom detection callbacks (onDetection is safe, but other hooks may not be).

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/b43950ee80a9128e. Report an issue: GitHub.