mastra-ai/mastra · error · Error

Subconscious pins.maxPins must be a positive integer.

Error message

Subconscious pins.maxPins must be a positive integer.

What it means

When pins are enabled in Subconscious config, pins.maxPins must be a positive integer (>= 1). Pins are stored per scope, and a non-positive or non-integer maxPins makes the pin store incoherent, so the constructor throws. Note maxPins has no default override here — it must be valid whenever pins !== false.

Source

Thrown at packages/memory/src/processors/observational-memory/subconscious/index.ts:119

    if (
      recentUpdates !== false &&
      (!Number.isInteger(recentUpdates) || recentUpdates < 1 || recentUpdates > MAX_RECENT_UPDATES)
    ) {
      throw new Error(`Subconscious activity.recentUpdates must be an integer between 1 and ${MAX_RECENT_UPDATES}.`);
    }

    const pins =
      config.pins === undefined || config.pins === false
        ? false
        : {
            maxPins: (config.pins === true ? undefined : config.pins.maxPins) ?? DEFAULT_MAX_PINS,
            maxCharacters:
              (config.pins === true ? undefined : config.pins.maxCharacters) ?? DEFAULT_PINNED_MAX_CHARACTERS,
            capturePinning: (config.pins === true ? undefined : config.pins.capturePinning) ?? false,
          };
    if (pins !== false) {
      if (!Number.isInteger(pins.maxPins) || pins.maxPins < 1) {
        throw new Error('Subconscious pins.maxPins must be a positive integer.');
      }
      if (
        !Number.isInteger(pins.maxCharacters) ||
        pins.maxCharacters < 1 ||
        pins.maxCharacters > MAX_PINNED_MAX_CHARACTERS
      ) {
        throw new Error(
          `Subconscious pins.maxCharacters must be an integer between 1 and ${MAX_PINNED_MAX_CHARACTERS}.`,
        );
      }
    }

    if (
      config.curationCadence !== undefined &&
      (!Number.isInteger(config.curationCadence) || config.curationCadence < 1)
    ) {
      throw new Error('Subconscious curationCadence must be a positive integer.');
    }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set pins.maxPins to a positive integer (e.g. 10).
2. Use pins: false (not an empty object) to disable pinning entirely.
3. Coerce/validate config values with Number.isInteger before constructing.

Example fix

// before
new Subconscious({ pins: { maxPins: 0 } })
// after
new Subconscious({ pins: { maxPins: 20 } })

if (config.pins && config.pins !== true) {
  const mp = config.pins.maxPins;
  if (!Number.isInteger(mp) || mp < 1) throw new Error('pins.maxPins must be a positive integer');
}

function isValidPinsConfig(p: unknown): p is { maxPins: number; maxCharacters?: number } {
  return typeof p === 'object' && p !== null && Number.isInteger((p as { maxPins?: unknown }).maxPins) && (p as { maxPins: number }).maxPins >= 1;
}

try {
  const sub = new Subconscious(config);
} catch (err) {
  if (err.message.includes('pins.maxPins')) {
    throw new ConfigError('Set pins.maxPins to a positive integer, or use pins: false to disable');
  } else throw err;
}

When it happens

Trigger: Configuring pins: { maxPins: 0 }, maxPins: -1, a float, or omitting maxPins while pins is an object and the resolved default is somehow invalid; passing a string value from parsed config.

Common situations: Disabling pins with pins: {} instead of pins: false (making the maxPins check run); env-sourced config producing strings; arithmetic on maxPins yielding 0 (e.g. Math.floor of a small fraction).

Related errors

• Subconscious semantic knowledge requires a vector store. Pas
• Subconscious semantic knowledge requires an embedder. Pass a
• Subconscious ${phase} agent name is required.
• Duplicate Subconscious ${phase} agent: ${name}
• Subconscious maxSteps must be an integer between 1 and ${MAX

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