mastra-ai/mastra · error · Error

Subconscious pins.maxCharacters must be an integer between 1

Error message

Subconscious pins.maxCharacters must be an integer between 1 and ${MAX_PINNED_MAX_CHARACTERS}.

What it means

When pins are enabled, pins.maxCharacters limits each pinned record's character budget and must be an integer within [1, MAX_PINNED_MAX_CHARACTERS]. Values outside that range throw at construction. The default (DEFAULT_PINNED_MAX_CHARACTERS) applies only when maxCharacters is undefined.

Source

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

    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.');
    }

    this.config = Object.freeze({ ...config, observation: [...observation], reflection: [...reflection] });
    this.resolved = Object.freeze({
      observation: observation.map(entry =>
        entryName(entry) === 'remind'
          ? resolveAgent(entry, BUILT_IN_OBSERVATION, config.model, maxSteps)
          : resolveExtractor(entry),

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set maxCharacters to an integer between 1 and MAX_PINNED_MAX_CHARACTERS.
2. Omit maxCharacters to use DEFAULT_PINNED_MAX_CHARACTERS.
3. Coerce and validate with Number.isInteger before constructing Subconscious.

Example fix

// before
new Subconscious({ pins: { maxPins: 10, maxCharacters: 0 } })
// after
new Subconscious({ pins: { maxPins: 10, maxCharacters: 2000 } })

const mc = config.pins === true ? undefined : config.pins?.maxCharacters;
if (mc !== undefined && (!Number.isInteger(mc) || mc < 1 || mc > MAX_PINNED_MAX_CHARACTERS)) {
  throw new Error(`maxCharacters must be an integer between 1 and ${MAX_PINNED_MAX_CHARACTERS}`);
}

function isValidMaxCharacters(v: unknown): v is number {
  return Number.isInteger(v) && (v as number) >= 1 && (v as number) <= MAX_PINNED_MAX_CHARACTERS;
}

try {
  const sub = new Subconscious(config);
} catch (err) {
  if (err.message.includes('maxCharacters')) {
    throw new ConfigError('pins.maxCharacters out of range in Subconscious config');
  } else throw err;
}

When it happens

Trigger: Configuring pins: { maxCharacters: 0 }, a negative number, a float, or a value exceeding MAX_PINNED_MAX_CHARACTERS; passing a string from parsed JSON/env config.

Common situations: Trying to shrink prompts to near-zero and setting 0; setting a huge budget above the hard cap; string values from env-derived configuration.

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