thedotmack/claude-mem · error · Error

chroma-mcp tool " " returned error

Error message

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

What it means

Error thrown when the chroma-mcp server responds successfully at the transport level but flags the result as an MCP tool error (result.isError true). The manager extracts the first text content item as the error detail (falling back to 'Unknown chroma-mcp error') and rethrows it as a plain Error naming the tool. This is an application-level error from the Chroma tool itself, not a connection problem.

Solutions

  1. Read the wrapped errorText — it contains chroma-mcp's own diagnostic for the failing tool call.
  2. Verify the tool name and argument schema against the installed chroma-mcp version (argument mismatches are the most common cause).
  3. Ensure the target collection exists before querying/updating/deleting it (call chroma_list_collections first).
  4. Check embedding dimension consistency between indexed and queried documents.
  5. Inspect the ChromaDB persistence directory for permission or corruption problems.
  6. Catch this error and surface the embedded errorText to the caller for targeted handling.

Example fix

// before
await manager.callTool('chroma_delete_documents', { collectionName: 'my-col', ids: ['x'] });
// Error: tool returned error: Collection my-col does not exist
// after
const collections = await manager.callTool('chroma_list_collections', {});
if (JSON.stringify(collections).includes('my-col')) {
  await manager.callTool('chroma_delete_documents', { collectionName: 'my-col', ids: ['x'] });
}
Defensive patterns

Strategy: validation

Validate before calling

// Validate arguments and collection existence before calling the tool
const cols = await manager.callTool('chroma_list_collections', {});
const exists = JSON.stringify(cols).includes('"my-collection"');
if (!exists) throw new Error('collection my-collection does not exist');
if (!Array.isArray(ids) || ids.length === 0) throw new Error('ids must be a non-empty array');

Type guard

function isToolError(e: unknown): boolean {
  return e instanceof Error && /^chroma-mcp tool ".+" returned error: /.test(e.message);
}
function extractToolErrorText(e: unknown): string | null {
  const m = (e as Error)?.message?.match(/returned error: (.+)$/);
  return m ? m[1] : null;
}

Try / catch

try {
  await manager.callTool('chroma_query_documents', args);
} catch (e) {
  const detail = /returned error: (.+)$/.exec((e as Error)?.message ?? '')?.[1];
  if (detail?.includes('does not exist')) {
    // create collection or skip
  } else { throw e; }
}

Prevention

When it happens

Trigger: Any callTool() invocation where chroma-mcp returns isError=true — e.g. chroma_add_documents with an invalid collection name, chroma_query_documents on a nonexistent collection, malformed arguments rejected by the tool, or ChromaDB-side failures surfaced as MCP tool errors.

Common situations: Querying/deleting a collection that was never created (typo'd collection name); passing wrong argument types (e.g. ids as string instead of array); embedding function mismatch causing dimension errors on add; ChromaDB storage directory permission or corruption issues.

Related errors

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

Appendix: source

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

      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 d8bc9755e7)