thedotmack/claude-mem · error · Error

chroma-mcp tool "${toolName}" returned error: ${errorText}

Error message

chroma-mcp tool "${toolName}" returned error: ${errorText}

What it means

Thrown when a chroma-mcp tool call returned a well-formed MCP response but result.isError is true. The manager extracts the first text content item as errorText (defaulting to 'Unknown chroma-mcp error') and throws a plain Error naming the tool and the embedded error text. This is an application-level error from inside chroma-mcp (e.g. invalid collection, bad query args), not a transport failure.

Source

Thrown at src/services/sync/ChromaMcpManager.ts:761

      try {
        if (callGeneration !== this.connectionGeneration) {
          throw new ChromaMcpConnectionCancelledError('chroma-mcp call cancelled during shutdown');
        }
        await this.ensureConnected();
        result = await this.client!.callTool({
          name: toolName,
          arguments: toolArguments
        });
      } catch (retryError) {
        this.connected = false;
        throw new Error(`chroma-mcp transport error during "${toolName}" (retry failed): ${retryError instanceof Error ? retryError.message : String(retryError)}`);
      }
    }

    if (result.isError) {
      const errorText = (result.content as Array<{ type: string; text?: string }>)
        ?.find(item => item.type === 'text')?.text || 'Unknown chroma-mcp error';
      throw new Error(`chroma-mcp tool "${toolName}" returned error: ${errorText}`);
    }

    const contentArray = result.content as Array<{ type: string; text?: string }>;
    if (!contentArray || contentArray.length === 0) {
      return null;
    }

    const firstTextContent = contentArray.find(item => item.type === 'text' && item.text);
    if (!firstTextContent || !firstTextContent.text) {
      return null;
    }

    try {
      return JSON.parse(firstTextContent.text);
    } catch (parseError: unknown) {
      if (parseError instanceof Error) {
        logger.debug('CHROMA_MCP', 'Non-JSON response from tool, returning null', {
          toolName,

View on GitHub (pinned to d768ba3643)

Solutions

1. Read the errorText in the message — it is chroma-mcp's own explanation and usually names the exact problem (e.g. 'Collection not found').
2. If the collection is missing, ensure ensureCollectionExists ran successfully for the collection_name in the call.
3. Validate toolArguments shape (collection_name, where filter syntax, include array) against the chroma-mcp version in use.
4. If embeddings/dimensions mismatch after a model change, re-create the collection and re-backfill.
5. Bump or pin chroma-mcp to a version whose tool names/args match what ChromaMcpManager emits.

Example fix

// before: querying a collection that may not exist yet
await chromaMcp.callTool('chroma_query_documents', { collection_name: name, ... });
// after: ensure the collection exists first, then query
await chromaMcp.callTool('chroma_get_or_create_collection', { collection_name: name });
await chromaMcp.callTool('chroma_query_documents', { collection_name: name, ... });

// Validate collection exists and args shape before calling
async function safeQuery(manager, collectionName: string, args: Record<string, unknown>) {
  await manager.callTool('chroma_get_or_create_collection', { collection_name: collectionName });
  return manager.callTool('chroma_query_documents', { collection_name: collectionName, ...args });
}

function isToolReturnedError(e: unknown): boolean {
  return e instanceof Error && /chroma-mcp tool ".*" returned error:/i.test(e.message);
}

try { return await manager.callTool(toolName, args); }
catch (e) {
  if (isToolReturnedError(e)) { log.warn('chroma tool error', { tool: toolName, msg: e.message }); return null; }
  throw e;
}

When it happens

Trigger: callTool('chroma_query_documents'|'chroma_add_documents'|...) reached the subprocess, which returned isError=true — typical causes: querying/upserting a non-existent collection_name, malformed where-filter, dimension mismatch between embedding and collection, or chroma internal errors surfaced as text.

Common situations: Querying before the collection was created (collection_name mismatch); embedding model/dimension change after the collection was created; passing a whereFilter whose operators chroma rejects; chroma version upgrade that renamed a tool or changed an argument.

Related errors

• chroma-mcp transport error during "${toolName}" (retry faile
• "${key}" is required
• Unknown tool: ${name}
• observation_add: "content" is required
• observation_record_event: "eventType" is required

AI-assisted analysis of thedotmack/claude-mem@d768ba3643 (2026-08-12). Data as JSON: /api/errors/c4acca62874f409f. Report an issue: GitHub.