mastra-ai/mastra · error · MastraError

VECTOR_INVALID_ID

VECTOR_INVALID_ID

Error message

Vector id must be provided and cannot be empty

What it means

The MastraVector base-class constructor requires a non-empty string id identifying the store instance. Passing a missing, non-string, or whitespace-only id is treated as a configuration error and throws immediately at instantiation.

Source

Thrown at packages/core/src/vector/vector.ts:78

/**
 * Type guard to check if an embedding model is a supported modern version (V2 or V3).
 * Use embedV2 for V2 models, embedV3 for V3 models, and embedV1 for legacy V1 models.
 */
export const isSupportedEmbeddingModel = <T>(
  model: MastraEmbeddingModel<T>,
): model is MastraSupportedEmbeddingModel<T> => {
  return supportedEmbeddingModelSpecifications.includes(
    model.specificationVersion as (typeof supportedEmbeddingModelSpecifications)[number],
  );
};

export abstract class MastraVector<Filter = VectorFilter> extends MastraBase {
  id: string;
  disableInit: boolean = false;

  constructor({ id, disableInit }: { id: string; disableInit?: boolean }) {
    if (!id || typeof id !== 'string' || id.trim() === '') {
      throw new MastraError({
        id: 'VECTOR_INVALID_ID',
        text: 'Vector id must be provided and cannot be empty',
        domain: ErrorDomain.MASTRA_VECTOR,
        category: ErrorCategory.USER,
      });
    }
    super({ name: 'MastraVector', component: 'VECTOR' });
    this.id = id;
    this.disableInit = disableInit ?? false;
  }

  get indexSeparator(): string {
    return '_';
  }

  abstract query(params: QueryVectorParams<Filter>): Promise<QueryResult[]>;
  // Adds type checks for positional arguments if used
  abstract upsert(params: UpsertVectorParams): Promise<string[]>;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a non-empty string id: new PgVector({ id: 'pg-main', connectionString })
2. Check the config source — log or assert the id value before construction
3. Give a literal default id instead of an env-derived one when unsure

Example fix

// before
const store = new PgVector({ id: process.env.VECTOR_ID, connectionString });
// after
const store = new PgVector({ id: process.env.VECTOR_ID || 'pg-main', connectionString });

function assertStoreId(id: unknown): asserts id is string {
  if (typeof id !== 'string' || id.trim() === '') throw new Error('vector store id required');
}

function isValidStoreId(v: unknown): v is string {
  return typeof v === 'string' && v.trim().length > 0;
}

try {
  const store = new PgVector({ id, connectionString });
} catch (e) {
  if (e instanceof MastraError && e.id === 'VECTOR_INVALID_ID') {
    throw new Error('VECTOR_ID config missing — set a non-empty store id');
  }
  throw e;
}

When it happens

Trigger: new MyVectorStore({ id: '' }), forgetting the id option entirely, passing id from an unset env/config variable, or passing a non-string (number/symbol).

Common situations: Reading id from process.env that was never set; template config spread that drops the id; renaming a config key so id falls through as undefined.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Better Auth instance is required. Please provide the auth op
• Okta domain is required. Provide it in the options or set OK
• Okta client ID is required. Provide it in the options or set
• MastraFactory: 'storage' is required. Pass a FactoryStorage
• GitHub reconcile worker requires a pull request or issue rec

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