mastra-ai/mastra · error · MastraError

OBSERVABILITY_INVALID_CONFIG

OBSERVABILITY_INVALID_CONFIG

Error message

Invalid observability configuration: ${errorMessages}

What it means

MastraError with id OBSERVABILITY_INVALID_CONFIG thrown from the observability DefaultObservability constructor when the top-level observability options fail Zod schema validation. The message embeds each Zod issue formatted as 'path: message' joined by semicolons, so it pinpoints exactly which option is wrong. It is categorized USER because it always reflects a caller-supplied configuration problem, not an internal fault.

Source

Thrown at observability/mastra/src/default.ts:86

    super({
      component: RegisteredLogger.OBSERVABILITY,
      name: 'Observability',
    });

    if (config === undefined) {
      config = {};
    }

    // Validate config with Zod
    const validationResult = observabilityRegistryConfigSchema.safeParse(config);
    if (!validationResult.success) {
      const errorMessages = validationResult.error.issues
        .map(
          (err: { path: (string | number | symbol)[]; message: string }) =>
            `${err.path.join('.') || 'config'}: ${err.message}`,
        )
        .join('; ');
      throw new MastraError({
        id: 'OBSERVABILITY_INVALID_CONFIG',
        text: `Invalid observability configuration: ${errorMessages}`,
        domain: ErrorDomain.MASTRA_OBSERVABILITY,
        category: ErrorCategory.USER,
        details: {
          validationErrors: errorMessages,
        },
      });
    }

    // Validate individual configs if they are plain objects (not instances)
    if (config.configs) {
      for (const [name, configValue] of Object.entries(config.configs)) {
        if (!isInstance(configValue)) {
          const configValidation = observabilityConfigValueSchema.safeParse(configValue);
          if (!configValidation.success) {
            const errorMessages = configValidation.error.issues
              .map(

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the validationErrors detail (and the message) to find the exact path and message of the failing option, e.g. 'exporting: expected object, received string'.
2. Fix the named option to match the observability schema: booleans as booleans, exporter config as an object like { exporters: [...] }.
3. Compare against the current Mastra observability docs for your version and remove deprecated/renamed options.
4. Log or print the config object you pass and validate it with the same schema (or JSON.stringify it) before constructing to spot shape mismatches.

Example fix

// before
new DefaultObservability({ exporting: 'true' });
// after
new DefaultObservability({ exporting: true });

// validate config against the same schema before constructing
import { observabilityConfigSchema } from '@mastra/core/observability'; // or the package's exported schema
const result = observabilityConfigSchema.safeParse(myConfig);
if (!result.success) {
  console.error('Invalid observability config:', result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`));
}

function isObservabilityError(e: unknown): e is { id: string; details?: { validationErrors?: string } } {
  return typeof e === 'object' && e !== null && 'id' in e && (e as any).id === 'OBSERVABILITY_INVALID_CONFIG';
}

try {
  const obs = new DefaultObservability(config);
} catch (err) {
  if (err instanceof MastraError && err.id === 'OBSERVABILITY_INVALID_CONFIG') {
    console.error('Observability config rejected:', err.details?.validationErrors);
    throw new Error(`Fix observability config: ${err.message}`);
  }
  throw err;
}

When it happens

Trigger: Calling `new DefaultObservability(config)` (directly or via Mastra's observability option) with an invalid top-level config: unknown option names, wrong option types (e.g. exporting: 'yes' instead of a boolean or object), or values outside allowed ranges — anything the schema rejects.

Common situations: Typos in option names like `exportor` instead of `exporters`; passing a string where an object is expected (exporting: 'true'); upgrading Mastra and using a removed/renamed option; copying a config snippet from a different Mastra version.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• OBSERVABILITY_INVALID_INSTANCE_CONFIG
• Unable to locate pricing data JSONL at any known path: ${can
• defaultProjectName is required when mode is "create"
• MASTRA_OBSERVABILITY_STORAGE_NOT_AVAILABLE
• TokenCostControl requires observability storage with getMetr

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