mastra-ai/mastra · error · MastraError

OBSERVABILITY_INVALID_INSTANCE_CONFIG

OBSERVABILITY_INVALID_INSTANCE_CONFIG

Error message

Invalid configuration for observability instance '${name}': ${errorMessages}

What it means

MastraError with id OBSERVABILITY_INVALID_INSTANCE_CONFIG thrown from the observability DefaultObservability constructor when one named instance under `instances` fails Zod schema validation. Unlike OBSERVABILITY_INVALID_CONFIG (top-level), this error names the failing instance in the message and details.instanceName, with per-issue 'path: message' strings. It is a USER-category error reflecting a malformed per-instance configuration object.

Source

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

        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(
                (err: { path: (string | number | symbol)[]; message: string }) =>
                  `${err.path.join('.')}: ${err.message}`,
              )
              .join('; ');
            throw new MastraError({
              id: 'OBSERVABILITY_INVALID_INSTANCE_CONFIG',
              text: `Invalid configuration for observability instance '${name}': ${errorMessages}`,
              domain: ErrorDomain.MASTRA_OBSERVABILITY,
              category: ErrorCategory.USER,
              details: {
                instanceName: name,
                validationErrors: errorMessages,
              },
            });
          }
        }
      }
    }

    // Resolve sensitive data filter setting (defaults to enabled).
    const sensitiveDataFilterSetting = config.sensitiveDataFilter ?? true;
    const shouldAutoApplySensitiveFilter = sensitiveDataFilterSetting !== false;
    const sensitiveDataFilterOptions: SensitiveDataFilterOptions | undefined =

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use the instanceName detail and the message's per-path messages to identify which named instance and which field is invalid.
2. Correct that instance's config to satisfy the observability instance schema (same option rules as the top-level config).
3. Validate the whole instances object against the schema or run it through the same Zod parser in a test to catch all bad instances at once.
4. Check the docs/changelog for your Mastra version to ensure instance-level options have not changed shape.

Example fix

// before
new DefaultObservability({ instances: { prod: { exporters: 'traces' } } });
// after
new DefaultObservability({ instances: { prod: { exporters: [{ type: 'traces', /* ... */ }] } } });

// validate each named instance before constructing
for (const [name, inst] of Object.entries(instances ?? {})) {
  const res = observabilityInstanceConfigSchema.safeParse(inst);
  if (!res.success) {
    console.error(`Instance '${name}' invalid:`, res.error.issues.map(i => `${i.path.join('.')}: ${i.message}`));
  }
}

function isInvalidInstanceConfigError(e: unknown): e is MastraError & { details: { instanceName: string; validationErrors?: string } } {
  return e instanceof MastraError && e.id === 'OBSERVABILITY_INVALID_INSTANCE_CONFIG';
}

try {
  const obs = new DefaultObservability({ instances });
} catch (err) {
  if (err instanceof MastraError && err.id === 'OBSERVABILITY_INVALID_INSTANCE_CONFIG') {
    const bad = (err.details as { instanceName?: string }).instanceName;
    console.error(`Fix observability instance '${bad}':`, err.details?.validationErrors);
    throw err;
  }
  throw err;
}

When it happens

Trigger: Passing an `instances` record to DefaultObservability where at least one entry (e.g. `instances: { prod: { ... } }`) has invalid fields — bad option names, wrong types, or invalid values — detected during the constructor's per-instance configValidation.

Common situations: Mixing top-level-only options into an instance config; a typo in one instance while others are valid; renaming or restructuring instances after a Mastra version upgrade; templating errors that render one instance's config as a string or drop a required field.

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_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/b63ca6f74c7c626c. Report an issue: GitHub.