From 8639be6e91050b8024852212c28a2639b7e6e93c Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Wed, 18 Nov 2026 13:33:43 -0600 Subject: [PATCH 1/4] fix(mcp): explain hasToken() separator errors in query tools --- .changeset/mcp-hastoken-separator-hint.md | 10 +++++++ packages/api/src/mcp/__tests__/query.test.ts | 27 +++++++++++++++++++ .../src/mcp/__tests__/queryTool.int.test.ts | 27 +++++++++++++++++++ packages/api/src/mcp/tools/query/helpers.ts | 25 ++++++++++++++++- packages/api/src/mcp/tools/query/schemas.ts | 4 ++- 5 files changed, 91 insertions(+), 2 deletions(-) create mode 100644 .changeset/mcp-hastoken-separator-hint.md diff --git a/.changeset/mcp-hastoken-separator-hint.md b/.changeset/mcp-hastoken-separator-hint.md new file mode 100644 index 0000000000..bec7eccb22 --- /dev/null +++ b/.changeset/mcp-hastoken-separator-hint.md @@ -0,0 +1,10 @@ +--- +'@hyperdx/api': patch +--- + +fix(mcp): explain hasToken() separator errors in query tools + +When a SQL filter calls `hasToken()` with a needle that contains `_`, `-`, `.`, +`@`, `:` or spaces, ClickHouse fails with "Needle must not contain whitespace or +separator characters". MCP query tools now append a hint pointing to a Lucene +term or `hasAllTokens()`/`LIKE`, and the `where` description warns about it. diff --git a/packages/api/src/mcp/__tests__/query.test.ts b/packages/api/src/mcp/__tests__/query.test.ts index c45606b11a..1320cd25c3 100644 --- a/packages/api/src/mcp/__tests__/query.test.ts +++ b/packages/api/src/mcp/__tests__/query.test.ts @@ -318,6 +318,33 @@ describe('errorHint', () => { expect(hint).not.toContain('clickstack_list_sources'); }); + it('explains hasToken separators in agent-written SQL filters', () => { + const hint = errorHint( + "Code: 36. DB::Exception: Needle must not contain whitespace or separator characters: while executing 'FUNCTION hasToken(message : 0, 'payment_failed'_String :: 1)'. (BAD_ARGUMENTS)", + ); + expect(hint).toContain('hasToken() takes a single token'); + expect(hint).toContain('lucene'); + expect(hint).toContain('hasAllTokens'); + }); + + it('keeps the hasToken hint if ClickHouse rewords the message', () => { + const message = + "Token argument contains a separator: while executing 'FUNCTION hasToken(message : 0, 'payment_failed'_String :: 1)'"; + const cause = new ClickHouseError({ + message, + code: '36', + type: 'BAD_ARGUMENTS', + }); + const hint = errorHint(message, new Error(message, { cause })); + expect(hint).toContain('hasToken() takes a single token'); + }); + + it('does not show the hasToken hint for other BAD_ARGUMENTS errors', () => { + const message = + "Code: 36. DB::Exception: Argument for function 'splitByChar' must be a single character. (BAD_ARGUMENTS)"; + expect(errorHint(message) ?? '').not.toContain('hasToken'); + }); + it('should NOT match lowercase "as" in cast expressions', () => { const hint = errorHint( 'Syntax error: cannot cast as Float64 near token...', diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts index e47b9cbc2e..2b36b642e3 100644 --- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts +++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts @@ -561,6 +561,33 @@ describe('MCP Query Tools', () => { expect(output).toHaveProperty('result'); }); + // Runs against the real ClickHouse image so a reworded error, which would + // silently drop the hint, fails here when the image is bumped. + it('hints at Lucene when a SQL filter passes a separator to hasToken', async () => { + const now = new Date(); + await bulkInsertLogs([ + { + Body: 'payment_failed for order', + ServiceName: 'billing', + SeverityText: 'ERROR', + Timestamp: new Date(now.getTime() - 60 * 1000), + }, + ]); + + const result = await callTool(client, 'clickstack_search', { + sourceId: logSource._id.toString(), + where: "hasToken(Body, 'payment_failed')", + whereLanguage: 'sql', + startTime: new Date(now.getTime() - 10 * 60 * 1000).toISOString(), + endTime: new Date(now.getTime() + 60 * 1000).toISOString(), + }); + + expect(result.isError).toBe(true); + expect(getFirstText(result)).toContain( + 'HINT: hasToken() takes a single token', + ); + }); + describe('denoise with seeded data', () => { const now = new Date(); const fiveMinAgo = new Date(now.getTime() - 5 * 60 * 1000); diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts index 63f5d9a668..cc55b02b1a 100644 --- a/packages/api/src/mcp/tools/query/helpers.ts +++ b/packages/api/src/mcp/tools/query/helpers.ts @@ -42,7 +42,10 @@ import { isConfigTile, } from '@/routers/external-api/v2/utils/dashboards'; import { isQueryTimeoutError } from '@/tasks/checkAlerts/errors'; -import { isClickHouseError } from '@/utils/clickhouseErrors'; +import { + getClickHouseErrorType, + isClickHouseError, +} from '@/utils/clickhouseErrors'; import { trimToolResponse } from '@/utils/trimToolResponse'; import type { ExternalDashboardTileWithId } from '@/utils/zod'; import { externalDashboardTileSchemaWithId } from '@/utils/zod'; @@ -1001,6 +1004,26 @@ export function errorHint( 'Bare ISO 8601 strings will NOT auto-cast to DateTime/DateTime64.' ); } + // hasToken() accepts one token of ASCII letters and digits; '_', '-', '.', + // '@', ':' and spaces are separators. Agents reach for it in SQL filters + // with ids, emails and snake_case names. The BAD_ARGUMENTS + hasToken + // fallback keeps the hint if ClickHouse rewords the message. + if ( + /Needle must not contain whitespace or separator characters/i.test(msg) || + (/\bhasToken\b/.test(msg) && + (getClickHouseErrorType(error) === 'BAD_ARGUMENTS' || + /BAD_ARGUMENTS|Code: 36\b/.test(msg))) + ) { + return ( + 'hasToken() takes a single token of letters and digits; "_", "-", ".", ' + + '"@", ":" and spaces all split tokens, so a needle like payment_failed, ' + + 'a UUID or an email is rejected. Put the term in a Lucene filter ' + + '(whereLanguage:"lucene", e.g. "payment_failed"), which splits it into ' + + 'tokens and still uses the text index. In SQL, use ' + + "hasAllTokens(col, 'payment_failed') AND col LIKE '%payment_failed%' " + + "for an exact match, or position(col, 'payment_failed') > 0." + ); + } if (/Syntax error.*\bAS\b/.test(msg)) { return ( 'Quote the alias if it contains reserved words or special chars: ' + diff --git a/packages/api/src/mcp/tools/query/schemas.ts b/packages/api/src/mcp/tools/query/schemas.ts index 9b2850266a..5de62e7c15 100644 --- a/packages/api/src/mcp/tools/query/schemas.ts +++ b/packages/api/src/mcp/tools/query/schemas.ts @@ -27,7 +27,9 @@ const WHERE_DESCRIPTION = ' when the source has one. With an index it matches whole tokens: timeout does not match ConnectionTimeoutException.\n' + " For a substring inside a word, use SQL ILIKE '%timeout%' (reads the whole column).\n" + ' Body:timeout, Body LIKE and Body ILIKE read the whole column, and Body:"..." is exact equality on the\n' + - ' whole body.'; + ' whole body.\n' + + " In SQL, hasToken(Body, 'x') errors unless x is only letters and digits: _ - . @ : and spaces are\n" + + ' separators, so ids, emails and snake_case names fail. Use the Lucene term instead.'; const WHERE_LANGUAGE_DESCRIPTION = 'Language of the "where" filter. The syntax in "where" MUST match this setting.\n' + From 4402c553b174761f8ae388f535caa00734c46820 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Wed, 18 Nov 2026 13:51:12 -0600 Subject: [PATCH 2/4] fix(mcp): SQL-only hasToken hint for raw SQL, warn on all builder tools (review P2) --- packages/api/src/mcp/__tests__/query.test.ts | 24 ++++++++++++++++++++ packages/api/src/mcp/tools/query/helpers.ts | 14 ++++++++---- packages/api/src/mcp/tools/query/schemas.ts | 8 +++---- 3 files changed, 37 insertions(+), 9 deletions(-) diff --git a/packages/api/src/mcp/__tests__/query.test.ts b/packages/api/src/mcp/__tests__/query.test.ts index 1320cd25c3..4b858122c7 100644 --- a/packages/api/src/mcp/__tests__/query.test.ts +++ b/packages/api/src/mcp/__tests__/query.test.ts @@ -339,6 +339,30 @@ describe('errorHint', () => { expect(hint).toContain('hasToken() takes a single token'); }); + it('keeps the hasToken hint when BAD_ARGUMENTS is only in the message text', () => { + const hint = errorHint( + "Code: 36. DB::Exception: Token argument contains a separator: while executing 'FUNCTION hasToken(message : 0, 'payment_failed'_String :: 1)'. (BAD_ARGUMENTS)", + ); + expect(hint).toContain('hasToken() takes a single token'); + }); + + it('does not show the hasToken hint for a non-BAD_ARGUMENTS hasToken error', () => { + const hint = errorHint( + 'Code: 42. DB::Exception: Number of arguments for function hasToken does not match: passed 1, should be 2. (NUMBER_OF_ARGUMENTS_DOESNT_MATCH)', + ); + expect(hint ?? '').not.toContain('hasToken() takes a single token'); + }); + + it('gives raw SQL callers a SQL-only hasToken hint', () => { + const hint = errorHint( + "Code: 36. DB::Exception: Needle must not contain whitespace or separator characters: while executing 'FUNCTION hasToken(message : 0, 'payment_failed'_String :: 1)'. (BAD_ARGUMENTS)", + undefined, + { rawSql: true }, + ); + expect(hint).toContain('hasAllTokens'); + expect(hint).not.toContain('whereLanguage'); + }); + it('does not show the hasToken hint for other BAD_ARGUMENTS errors', () => { const message = "Code: 36. DB::Exception: Argument for function 'splitByChar' must be a single character. (BAD_ARGUMENTS)"; diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts index cc55b02b1a..c22fa71c79 100644 --- a/packages/api/src/mcp/tools/query/helpers.ts +++ b/packages/api/src/mcp/tools/query/helpers.ts @@ -1014,14 +1014,18 @@ export function errorHint( (getClickHouseErrorType(error) === 'BAD_ARGUMENTS' || /BAD_ARGUMENTS|Code: 36\b/.test(msg))) ) { + const sqlAlternatives = + "hasAllTokens(col, 'payment_failed') to match every token (uses a text " + + "index), or position(col, 'payment_failed') > 0 for the exact substring."; return ( 'hasToken() takes a single token of letters and digits; "_", "-", ".", ' + '"@", ":" and spaces all split tokens, so a needle like payment_failed, ' + - 'a UUID or an email is rejected. Put the term in a Lucene filter ' + - '(whereLanguage:"lucene", e.g. "payment_failed"), which splits it into ' + - 'tokens and still uses the text index. In SQL, use ' + - "hasAllTokens(col, 'payment_failed') AND col LIKE '%payment_failed%' " + - "for an exact match, or position(col, 'payment_failed') > 0." + 'a UUID or an email is rejected. ' + + (options?.rawSql + ? `Use ${sqlAlternatives}` + : 'Put the term in a Lucene filter (whereLanguage:"lucene", e.g. ' + + '"payment_failed"), which splits it into tokens and still uses the ' + + `text index. In SQL, use ${sqlAlternatives}`) ); } if (/Syntax error.*\bAS\b/.test(msg)) { diff --git a/packages/api/src/mcp/tools/query/schemas.ts b/packages/api/src/mcp/tools/query/schemas.ts index 5de62e7c15..2bbecc320d 100644 --- a/packages/api/src/mcp/tools/query/schemas.ts +++ b/packages/api/src/mcp/tools/query/schemas.ts @@ -27,9 +27,7 @@ const WHERE_DESCRIPTION = ' when the source has one. With an index it matches whole tokens: timeout does not match ConnectionTimeoutException.\n' + " For a substring inside a word, use SQL ILIKE '%timeout%' (reads the whole column).\n" + ' Body:timeout, Body LIKE and Body ILIKE read the whole column, and Body:"..." is exact equality on the\n' + - ' whole body.\n' + - " In SQL, hasToken(Body, 'x') errors unless x is only letters and digits: _ - . @ : and spaces are\n" + - ' separators, so ids, emails and snake_case names fail. Use the Lucene term instead.'; + ' whole body.'; const WHERE_LANGUAGE_DESCRIPTION = 'Language of the "where" filter. The syntax in "where" MUST match this setting.\n' + @@ -42,7 +40,9 @@ const WHERE_LANGUAGE_DESCRIPTION = 'For exact matching, quote the value (field:"value", case-sensitive) or use SQL: WHERE field = \'value\'. ' + "For reliable wildcards, use SQL: WHERE field LIKE 'val%'.\n\n" + 'Common mistake: writing Column:value (Lucene) but setting whereLanguage to "sql". ' + - 'If your filter uses colon syntax, use "lucene".'; + 'If your filter uses colon syntax, use "lucene".\n\n' + + "In SQL, hasToken(col, 'x') errors unless x is only letters and digits: _ - . @ : and spaces are " + + 'separators, so ids, emails and snake_case names fail. Search the term with Lucene instead.'; // ─── Shared Zod schemas ────────────────────────────────────────────────────── From 1325446a26a6a6ce2df42baaed6c4c058f9e3601 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Wed, 18 Nov 2026 14:07:43 -0600 Subject: [PATCH 3/4] fix(mcp): pin the exact term in the SQL hasToken hint (review P2) --- .changeset/mcp-hastoken-separator-hint.md | 3 ++- packages/api/src/mcp/__tests__/query.test.ts | 4 +++- packages/api/src/mcp/__tests__/queryTool.int.test.ts | 6 +++--- packages/api/src/mcp/tools/query/helpers.ts | 6 ++++-- 4 files changed, 12 insertions(+), 7 deletions(-) diff --git a/.changeset/mcp-hastoken-separator-hint.md b/.changeset/mcp-hastoken-separator-hint.md index bec7eccb22..92fd11d156 100644 --- a/.changeset/mcp-hastoken-separator-hint.md +++ b/.changeset/mcp-hastoken-separator-hint.md @@ -7,4 +7,5 @@ fix(mcp): explain hasToken() separator errors in query tools When a SQL filter calls `hasToken()` with a needle that contains `_`, `-`, `.`, `@`, `:` or spaces, ClickHouse fails with "Needle must not contain whitespace or separator characters". MCP query tools now append a hint pointing to a Lucene -term or `hasAllTokens()`/`LIKE`, and the `where` description warns about it. +term, or in SQL to `hasAllTokens()` plus `position()` for the exact term, and +the `whereLanguage` description warns about it. diff --git a/packages/api/src/mcp/__tests__/query.test.ts b/packages/api/src/mcp/__tests__/query.test.ts index 4b858122c7..5cc7a2079d 100644 --- a/packages/api/src/mcp/__tests__/query.test.ts +++ b/packages/api/src/mcp/__tests__/query.test.ts @@ -359,7 +359,9 @@ describe('errorHint', () => { undefined, { rawSql: true }, ); - expect(hint).toContain('hasAllTokens'); + expect(hint).toContain( + "hasAllTokens(col, 'payment_failed') AND position(col, 'payment_failed') > 0", + ); expect(hint).not.toContain('whereLanguage'); }); diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts index 2b36b642e3..767f561062 100644 --- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts +++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts @@ -583,9 +583,9 @@ describe('MCP Query Tools', () => { }); expect(result.isError).toBe(true); - expect(getFirstText(result)).toContain( - 'HINT: hasToken() takes a single token', - ); + const text = getFirstText(result); + expect(text).toContain('HINT: hasToken() takes a single token'); + expect(text).toContain('whereLanguage:"lucene"'); }); describe('denoise with seeded data', () => { diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts index c22fa71c79..7ccaf15c27 100644 --- a/packages/api/src/mcp/tools/query/helpers.ts +++ b/packages/api/src/mcp/tools/query/helpers.ts @@ -1014,9 +1014,11 @@ export function errorHint( (getClickHouseErrorType(error) === 'BAD_ARGUMENTS' || /BAD_ARGUMENTS|Code: 36\b/.test(msg))) ) { + // hasAllTokens alone matches the tokens in any order; position() pins the + // exact term without LIKE's '_' wildcard. const sqlAlternatives = - "hasAllTokens(col, 'payment_failed') to match every token (uses a text " + - "index), or position(col, 'payment_failed') > 0 for the exact substring."; + "hasAllTokens(col, 'payment_failed') AND position(col, 'payment_failed') > 0 " + + 'for the exact term (hasAllTokens lets a text index skip granules).'; return ( 'hasToken() takes a single token of letters and digits; "_", "-", ".", ' + '"@", ":" and spaces all split tokens, so a needle like payment_failed, ' + From 67634201baeba16417ae34b467e0402ba0fba257 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Wed, 18 Nov 2026 14:25:52 -0600 Subject: [PATCH 4/4] fix(mcp): lead the SQL hasToken hint with position() for older ClickHouse (review P2) --- .changeset/mcp-hastoken-separator-hint.md | 5 +++-- packages/api/src/mcp/__tests__/query.test.ts | 5 ++--- packages/api/src/mcp/tools/query/helpers.ts | 9 +++++---- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/.changeset/mcp-hastoken-separator-hint.md b/.changeset/mcp-hastoken-separator-hint.md index 92fd11d156..647db60442 100644 --- a/.changeset/mcp-hastoken-separator-hint.md +++ b/.changeset/mcp-hastoken-separator-hint.md @@ -7,5 +7,6 @@ fix(mcp): explain hasToken() separator errors in query tools When a SQL filter calls `hasToken()` with a needle that contains `_`, `-`, `.`, `@`, `:` or spaces, ClickHouse fails with "Needle must not contain whitespace or separator characters". MCP query tools now append a hint pointing to a Lucene -term, or in SQL to `hasAllTokens()` plus `position()` for the exact term, and -the `whereLanguage` description warns about it. +term, or in SQL to `position()` for the exact term (with `hasAllTokens()` as an +optional text-index speed-up), and the `whereLanguage` description warns about +it. diff --git a/packages/api/src/mcp/__tests__/query.test.ts b/packages/api/src/mcp/__tests__/query.test.ts index 5cc7a2079d..3789da7f2e 100644 --- a/packages/api/src/mcp/__tests__/query.test.ts +++ b/packages/api/src/mcp/__tests__/query.test.ts @@ -359,9 +359,8 @@ describe('errorHint', () => { undefined, { rawSql: true }, ); - expect(hint).toContain( - "hasAllTokens(col, 'payment_failed') AND position(col, 'payment_failed') > 0", - ); + expect(hint).toContain("Use position(col, 'payment_failed') > 0"); + expect(hint).toContain('If the column has a text index'); expect(hint).not.toContain('whereLanguage'); }); diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts index 7ccaf15c27..99809fdfc7 100644 --- a/packages/api/src/mcp/tools/query/helpers.ts +++ b/packages/api/src/mcp/tools/query/helpers.ts @@ -1014,11 +1014,12 @@ export function errorHint( (getClickHouseErrorType(error) === 'BAD_ARGUMENTS' || /BAD_ARGUMENTS|Code: 36\b/.test(msg))) ) { - // hasAllTokens alone matches the tokens in any order; position() pins the - // exact term without LIKE's '_' wildcard. + // position() works on every ClickHouse version and, unlike LIKE, has no '_' + // wildcard. hasAllTokens() is newer and only worth adding with a text index. const sqlAlternatives = - "hasAllTokens(col, 'payment_failed') AND position(col, 'payment_failed') > 0 " + - 'for the exact term (hasAllTokens lets a text index skip granules).'; + "position(col, 'payment_failed') > 0 for the exact term. If the column " + + "has a text index, prefix it with hasAllTokens(col, 'payment_failed') AND " + + 'so the index can skip granules.'; return ( 'hasToken() takes a single token of letters and digits; "_", "-", ".", ' + '"@", ":" and spaces all split tokens, so a needle like payment_failed, ' +