{"record":{"id":"37226cc728be0fc5","repo":"chroma-core/chroma","slug":"k-document-notcontains-requires-a-string-value","errorCode":null,"errorMessage":"K.DOCUMENT.notContains requires a string value","messagePattern":"K\\.DOCUMENT\\.notContains requires a string value","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/execution/expression/key.ts","lineNumber":79,"sourceCode":"    if (this.name === \"#document\" && typeof value !== \"string\") {\n      throw new TypeError(\"K.DOCUMENT.contains requires a string value\");\n    }\n    return createComparisonWhere(this.name, \"$contains\", value);\n  }\n\n  /**\n   * Not-contains filter.\n   *\n   * On `Key.DOCUMENT`: excludes documents containing the substring.\n   * On metadata fields: checks that the array field does not contain the scalar value.\n   *\n   * @example\n   * K.DOCUMENT.notContains(\"deprecated\")   // document substring exclusion\n   * K(\"tags\").notContains(\"draft\")          // metadata array not-contains\n   */\n  public notContains(value: string | number | boolean): WhereExpression {\n    if (this.name === \"#document\" && typeof value !== \"string\") {\n      throw new TypeError(\"K.DOCUMENT.notContains requires a string value\");\n    }\n    return createComparisonWhere(this.name, \"$not_contains\", value);\n  }\n\n  public regex(pattern: string): WhereExpression {\n    if (typeof pattern !== \"string\") {\n      throw new TypeError(\"$regex requires a string pattern\");\n    }\n    return createComparisonWhere(this.name, \"$regex\", pattern);\n  }\n\n  public notRegex(pattern: string): WhereExpression {\n    if (typeof pattern !== \"string\") {\n      throw new TypeError(\"$not_regex requires a string pattern\");\n    }\n    return createComparisonWhere(this.name, \"$not_regex\", pattern);\n  }\n}","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/execution/expression/key.ts#L61-L97","documentation":"K.DOCUMENT.notContains() excludes documents whose text contains a substring, so the value must be a string. Passing a number or boolean with K.DOCUMENT.notContains() raises a TypeError client-side, before any request is sent. Metadata-field keys accept string|number|boolean; the restriction applies only to the '#document' pseudo-key.","triggerScenarios":"K.DOCUMENT.notContains(0) or K.DOCUMENT.notContains(false). Common in generic exclusion filters that reuse one value across document and metadata keys.","commonSituations":"Building an exclusion list where some entries are numbers (IDs) and code forwards them verbatim to K.DOCUMENT. Passing falsy sentinels (0, false) intending 'exclude nothing'.","solutions":["Pass a string: K.DOCUMENT.notContains(\"deprecated\")","In shared filter code, convert values with String(value) when the target key is #document","Skip document-text exclusion entirely when the value is not a meaningful string"],"exampleFix":"// before\nK.DOCUMENT.notContains(excludeId); // excludeId = 0 -> TypeError\n\n// after\ntypeof excludeId === \"string\"\n  ? K.DOCUMENT.notContains(excludeId)\n  : K(\"owner_id\").notContains(excludeId);","handlingStrategy":"type-guard","validationCode":"const isDocumentExclusionValue = (key: Key, value: unknown): boolean =>\n  key !== K.DOCUMENT || typeof value === \"string\";\n\nif (!isDocumentExclusionValue(key, value)) {\n  throw new Error(\"Document exclusion filters require a string value\");\n}\nkey.notContains(value as string | number | boolean);","typeGuard":"function notContainsValueFor(key: Key, value: string | number | boolean): string | number | boolean {\n  return key.name === \"#document\" && typeof value !== \"string\" ? String(value) : value;\n}","tryCatchPattern":null,"preventionTips":["Route numeric/boolean exclusions to a metadata key, not K.DOCUMENT","Coerce values with String() when the target is document text","Keep exclusion lists typed as string[]"],"tags":["chroma","where-filter","document","typeerror"],"backgroundTag":"wrong-argument-type","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}