fix(knowledge): send tag filters as a JSON string so the document filter works

The document-list tag filter never reached the database. The `tagFilters`
query field was a Zod `.transform()` that decoded the JSON string into an
array of objects; the client's `requestJson` parses the query before
serializing, so `appendQuery` received the array and emitted
`tagFilters=[object Object]` into the URL. The route then failed to
`JSON.parse` it and returned 400, so the list came back empty (or stale via
keepPreviousData) regardless of operator or value.

- Model `tagFilters` as the wire string it actually is; decode it server-side
  via a new `parseDocumentTagFiltersParam` helper (route maps a bad value to 400).
- Harden `appendQuery`: throw on an array-of-objects query param instead of
  silently serializing `[object Object]`, so this whole class fails loudly.
- Default the text tag-filter operator to `contains` so a partial value matches.
- Tests: requestJson serializes the JSON param verbatim + the guard throws; the
  query schema keeps tagFilters a string; the decode helper round-trips.

A full sweep of every GET/DELETE contract query field confirmed this was the
only field of this class — logs filters and table filter/sort are unaffected.

Author: waleedlatif1

apps/sim/app/api/knowledge/[id]/documents/route.ts

@@ -8,6 +8,7 @@ import {
   bulkKnowledgeDocumentsContract,
   createKnowledgeDocumentsContract,
   listKnowledgeDocumentsQuerySchema,
+  parseDocumentTagFiltersParam,
 } from '@/lib/api/contracts/knowledge'
 import { parseRequest } from '@/lib/api/server'
 import { getSession } from '@/lib/auth'
@@ -67,6 +68,18 @@ export const GET = withRouteHandler(
       const { enabledFilter, search, limit, offset, sortBy, sortOrder, tagFilters } =
         queryResult.data
 
+      let parsedTagFilters: TagFilterCondition[] | undefined
+      try {
+        parsedTagFilters = parseDocumentTagFiltersParam(tagFilters) as
+          | TagFilterCondition[]
+          | undefined
+      } catch {
+        return NextResponse.json(
+          { error: 'tagFilters must be a valid JSON array' },
+          { status: 400 }
+        )
+      }
+
       const result = await getDocuments(
         knowledgeBaseId,
         {
@@ -76,7 +89,7 @@ export const GET = withRouteHandler(
           offset,
           ...(sortBy && { sortBy }),
           ...(sortOrder && { sortOrder }),
-          tagFilters: tagFilters as TagFilterCondition[] | undefined,
+          tagFilters: parsedTagFilters,
         },
         requestId
       )

apps/sim/app/workspace/[workspaceId]/knowledge/[id]/base.tsx

@@ -1466,11 +1466,25 @@ const createEmptyEntry = (): TagFilterEntry => ({
   tagName: '',
   tagSlot: '',
   fieldType: 'text',
-  operator: 'eq',
+  operator: 'contains',
   value: '',
   valueTo: '',
 })
 
+/**
+ * Default operator when a tag is selected. Text filters default to `contains`
+ * so typing part of a value finds matches (exact `equals` stays one click away
+ * in the operator dropdown); other field types keep their first, equality
+ * operator.
+ */
+function getDefaultOperatorForFieldType(
+  fieldType: FilterFieldType,
+  operators: ReturnType<typeof getOperatorsForFieldType>
+): string {
+  if (fieldType === 'text') return 'contains'
+  return operators[0]?.value ?? 'eq'
+}
+
 interface TagFilterSectionProps {
   tagDefinitions: TagDefinition[]
   entries: TagFilterEntry[]
@@ -1601,7 +1615,7 @@ function TagFilterSection({ tagDefinitions, entries, onChange }: TagFilterSectio
       tagName,
       tagSlot: def?.tagSlot || '',
       fieldType,
-      operator: operators[0]?.value || 'eq',
+      operator: getDefaultOperatorForFieldType(fieldType, operators),
       value: '',
       valueTo: '',
     })

apps/sim/lib/api/client/request.test.ts

@@ -0,0 +1,71 @@
+/**
+ * @vitest-environment node
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { requestJson } from '@/lib/api/client/request'
+import { listKnowledgeDocumentsContract } from '@/lib/api/contracts/knowledge'
+import { defineRouteContract } from '@/lib/api/contracts/types'
+
+/**
+ * Captures the URL of the last fetch call and returns a valid JSON response so
+ * `requestJson`'s response validation passes.
+ */
+function mockFetchReturning(body: unknown) {
+  const fetchMock = vi.fn(
+    async () =>
+      new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      })
+  )
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+describe('requestJson query serialization', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('serializes a JSON-string query param verbatim (regression: tagFilters)', async () => {
+    const fetchMock = mockFetchReturning({
+      success: true,
+      data: {
+        documents: [],
+        pagination: { total: 0, limit: 50, offset: 0, hasMore: false },
+      },
+    })
+
+    const tagFilters = JSON.stringify([
+      { tagSlot: 'tag1', fieldType: 'text', operator: 'contains', value: 'Ada Lovelace' },
+    ])
+
+    await requestJson(listKnowledgeDocumentsContract, {
+      params: { id: 'kb-1' },
+      query: { tagFilters },
+    })
+
+    const calledUrl = String(fetchMock.mock.calls[0][0])
+    const url = new URL(calledUrl, 'https://example.test')
+    // The param must round-trip as the exact JSON, never "[object Object]".
+    expect(url.searchParams.get('tagFilters')).toBe(tagFilters)
+    expect(calledUrl).not.toContain('object+Object')
+    expect(calledUrl).not.toContain('[object Object]')
+  })
+
+  it('throws instead of silently corrupting an array-of-objects query param', async () => {
+    mockFetchReturning({ ok: true })
+
+    const badContract = defineRouteContract({
+      method: 'GET',
+      path: '/api/test',
+      query: z.object({ items: z.array(z.object({ a: z.string() })) }),
+      response: { mode: 'json', schema: z.object({ ok: z.boolean() }) },
+    })
+
+    await expect(requestJson(badContract, { query: { items: [{ a: 'x' }] } })).rejects.toThrow(
+      /arrays of objects are not URL-safe/
+    )
+  })
+})

apps/sim/lib/api/client/request.ts

@@ -68,9 +68,19 @@ function appendQuery(path: string, query: unknown): string {
 
     if (Array.isArray(value)) {
       for (const item of value) {
-        if (item !== undefined && item !== null && item !== '') {
-          searchParams.append(key, String(item))
+        if (item === undefined || item === null || item === '') continue
+        // A non-scalar in a query array would stringify to "[object Object]" and
+        // silently corrupt the request. Encode such values as a single JSON
+        // string param and decode them server-side instead. Failing loudly here
+        // keeps the boundary honest (this is how the knowledge tagFilters bug
+        // shipped undetected).
+        if (typeof item === 'object') {
+          throw new Error(
+            `Cannot serialize query param "${key}": arrays of objects are not URL-safe — ` +
+              'encode the value as a JSON string param and decode it server-side.'
+          )
         }
+        searchParams.append(key, String(item))
       }
       continue
     }

apps/sim/lib/api/contracts/knowledge/documents.test.ts

@@ -0,0 +1,46 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  listKnowledgeDocumentsQuerySchema,
+  parseDocumentTagFiltersParam,
+} from '@/lib/api/contracts/knowledge/documents'
+
+describe('listKnowledgeDocumentsQuerySchema.tagFilters', () => {
+  it('keeps tagFilters a raw string (must NOT transform to an array)', () => {
+    // A transform-to-array here breaks requestJson outbound serialization
+    // (the array serializes as "[object Object]"). The wire type must stay a
+    // string; decoding happens server-side via parseDocumentTagFiltersParam.
+    const tagFilters = JSON.stringify([
+      { tagSlot: 'tag1', fieldType: 'text', operator: 'contains', value: 'x' },
+    ])
+    const parsed = listKnowledgeDocumentsQuerySchema.parse({ tagFilters })
+    expect(parsed.tagFilters).toBe(tagFilters)
+    expect(typeof parsed.tagFilters).toBe('string')
+  })
+})
+
+describe('parseDocumentTagFiltersParam', () => {
+  it('returns undefined for an absent param', () => {
+    expect(parseDocumentTagFiltersParam(undefined)).toBeUndefined()
+    expect(parseDocumentTagFiltersParam('')).toBeUndefined()
+  })
+
+  it('decodes a valid JSON array of filters', () => {
+    const filters = [
+      { tagSlot: 'tag1', fieldType: 'text', operator: 'contains', value: 'x' },
+      { tagSlot: 'date1', fieldType: 'date', operator: 'eq', value: '2026-04-21' },
+    ]
+    expect(parseDocumentTagFiltersParam(JSON.stringify(filters))).toEqual(filters)
+  })
+
+  it('throws on malformed JSON', () => {
+    expect(() => parseDocumentTagFiltersParam('[object Object]')).toThrow()
+    expect(() => parseDocumentTagFiltersParam('{not json')).toThrow()
+  })
+
+  it('throws when the shape is wrong', () => {
+    expect(() => parseDocumentTagFiltersParam(JSON.stringify([{ tagSlot: '' }]))).toThrow()
+  })
+})

apps/sim/lib/api/contracts/knowledge/documents.ts

@@ -40,20 +40,25 @@ export const listKnowledgeDocumentsQuerySchema = z.object({
     ])
     .optional(),
   sortOrder: z.enum(['asc', 'desc']).optional(),
-  tagFilters: z
-    .string()
-    .optional()
-    .transform((value, ctx) => {
-      if (!value) return undefined
-      try {
-        return z.array(documentTagFilterSchema).parse(JSON.parse(value))
-      } catch {
-        ctx.addIssue({ code: 'custom', message: 'tagFilters must be a valid JSON array' })
-        return z.NEVER
-      }
-    }),
+  // A query param is a string on the wire, so `tagFilters` is carried as a JSON
+  // string and decoded by the route via `parseDocumentTagFiltersParam`. It must
+  // NOT be a `.transform()` to an array here: the client's `requestJson` parses
+  // the query before serializing it, so a transform would turn the string into
+  // an array that serializes to `tagFilters=[object Object]` and 400s the route.
+  tagFilters: z.string().optional(),
 })
 
+/**
+ * Decodes the `tagFilters` query string (a JSON array) into validated filters.
+ * Throws on malformed JSON or a shape mismatch; callers map that to a 400.
+ */
+export function parseDocumentTagFiltersParam(
+  value: string | undefined
+): DocumentTagFilter[] | undefined {
+  if (!value) return undefined
+  return z.array(documentTagFilterSchema).parse(JSON.parse(value))
+}
+
 export const createDocumentBodySchema = z.object({
   filename: z.string().min(1, 'Filename is required'),
   fileUrl: knowledgeDocumentFileUrlSchema,