mastra-ai/mastra · error

Invalid state update: ${messages}

Error message

Invalid state update: ${messages}

What it means

State updates are merged with the current state and validated against the state's Standard Schema when one is configured. If validation produces issues, the library throws with the joined issue messages, and the state is left unchanged — guaranteeing #state always satisfies the schema.

Source

Thrown at packages/core/src/agent-controller/session.ts:2078

          }
        }
      }
    } catch {
      // Schema doesn't support JSON Schema extraction — skip defaults.
    }

    return defaults as Partial<TState>;
  }

  private async apply(updates: Partial<TState>, persistSetting?: PersistSettingFn): Promise<void> {
    const changedKeys = Object.keys(updates as Record<string, unknown>);
    const newState = { ...(this.#state as Record<string, unknown>), ...(updates as Record<string, unknown>) };

    if (this.#schema) {
      const result = await this.#schema['~standard'].validate(newState);
      if (result.issues) {
        const messages = result.issues.map(i => i.message).join('; ');
        throw new Error(`Invalid state update: ${messages}`);
      }
      this.#state = result.value as TState;
    } else {
      this.#state = newState as TState;
    }

    this.#bus.emit({ type: 'state_changed', state: this.get() as Record<string, unknown>, changedKeys });

    // Mirror restart-surviving preferences into thread metadata so they can be
    // restored by `Session.loadMetadata()` after the host process restarts.
    // Persistence failures never fail the in-memory state update.
    if (persistSetting) {
      const state = this.#state as Record<string, unknown>;
      for (const key of PERSISTED_STATE_KEYS) {
        if (!changedKeys.includes(key)) continue;
        try {
          await persistSetting({ key, value: state[key] });
        } catch {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the thrown messages to see which schema issues fired and fix the update payload accordingly.
2. Validate the merged object yourself with the same schema before calling update.
3. If a required field is only known later, make it optional/nullable in the schema or supply a default in the update.

Example fix

// before
await state.update({ count: '3' }); // Invalid state update: expected number
// after
const result = schema['~standard'].validate({ ...state.get(), count: 3 });
if (!result.issues) await state.update({ count: 3 });

const merged = { ...state.get(), ...updates };
const result = stateSchema['~standard'].validate(merged);
if (result.issues) throw new Error(result.issues.map(i => i.message).join('; '));

try {
  await state.update(updates);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Invalid state update: ')) {
    // parse e.message for issue details; fix payload or reset state
  } else throw e;
}

When it happens

Trigger: Calling update({ ... }) with values violating the schema (wrong types, missing required fields after merge, invalid enum values, cross-field invariant violations).

Common situations: Passing partial updates where the schema requires the merged result to be complete; string/number confusion (e.g. count: '3'); nulling a required field; schema tightened in an upgrade so previously-legal updates now fail.

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

• ${label} contains an unsupported field.
• Mode not found: ${modeId}
• SchemaValidationError(field, this.formatErrors(result.error)
• INVALID_DATA_ITEM
• We could not convert the schema to a JSONSchema

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