Invalid filter format: ${error instanceof Error ? error.mess

Error message

Invalid filter format: ${error instanceof Error ? error.message : String(error)}

What it means

parseFilterValue accepts a filter either as a string (parsed with JSON.parse) or as an object. When a string filter fails JSON.parse, this error is thrown wrapping the JSON parse message. It exists to give RAG tool callers a clear error instead of a raw SyntaxError.

Source

Thrown at packages/rag/src/utils/tool-helpers.ts:185

 * @param filter - The filter value to parse (string or object)
 * @param logger - Optional logger for error reporting
 * @returns Parsed filter object
 * @throws Error if filter is a string that cannot be parsed as JSON or if filter is not a plain object
 */
export function parseFilterValue(filter: unknown, logger?: Logger | null): Record<string, any> {
  if (!filter) {
    return {};
  }

  let parsedFilter = filter;
  if (typeof filter === 'string') {
    try {
      parsedFilter = JSON.parse(filter);
    } catch (error) {
      if (logger) {
        logger.error('Invalid filter', { filter, error });
      }
      throw new Error(`Invalid filter format: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

  // Validate that non-string filter is a plain object
  if (typeof parsedFilter !== 'object' || parsedFilter === null || Array.isArray(parsedFilter)) {
    const receivedType = Array.isArray(parsedFilter) ? 'array' : typeof parsedFilter;
    if (logger) {
      logger.error('Invalid filter', { filter, error: 'Filter must be a plain object' });
    }
    throw new Error(`Invalid filter format: expected a plain object, got ${receivedType}`);
  }

  return parsedFilter as Record<string, any>;
}

View on GitHub (pinned to 75dd419e61)

Solutions

Make the string valid JSON: double-quoted keys and string values, e.g. '{"category":"news"}'.
Better, pass the filter as a plain JavaScript object instead of a string so no parsing occurs.
Validate with JSON.parse in your own code before passing, and surface the parse error to the user.
If an LLM produces the filter, instruct it in the tool description to emit strict JSON filters.

Example fix

// before
await tool.execute({ filter: "{category: 'news'}" });
// after
await tool.execute({ filter: { category: 'news' } });

Defensive patterns

Strategy: validation

Validate before calling

function parseFilterInput(raw: string): Record<string, unknown> {
  let parsed: unknown;
  try { parsed = JSON.parse(raw); } catch (e) {
    throw new TypeError(`filter must be strict JSON: ${(e as Error).message}`);
  }
  return parsed as Record<string, unknown>;
}

Try / catch

try {
  await tool.execute({ filter: filterString });
} catch (e) {
  if ((e as Error).message.startsWith('Invalid filter format')) {
    // fall back to a default filter or re-prompt for a strict JSON filter
    return runWithDefaultFilter();
  }
  throw e;
}

Prevention

Pass filter objects, not strings, whenever possible.
Document/require strict JSON (double quotes, no trailing commas) in tool descriptions for LLM callers.
Validate filters at config load time with JSON.parse.

When it happens

Trigger: Passing a string to the `filter` option of a vector query tool that is not valid JSON — e.g. `"category == 'news'"`, `"{category: 'news'}"` (unquoted key), or a truncated JSON string.

Common situations: LLM-generated tool call arguments where the model emits a JS-style filter expression instead of JSON; users hand-writing filters in playground/config with single quotes or trailing commas; template strings interpolated with malformed values.

Related errors

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