krisk/Fuse · error · Error

Logical search is not available

Error message

Logical search is not available

What it means

Logical search ($and/$or object query expressions) is gated behind the LOGICAL_SEARCH_ENABLED environment variable. When Fuse.search receives an object query and the env var is unset, _searchLogical throws immediately instead of parsing the expression. This lets builds ship without the logical-parser code.

Source

Thrown at src/core/index.ts:361

          if (heap) {
            result.score = computeScoreSingle(result.matches, {
              ignoreFieldNorm
            })
            heap.insert(result)
          } else {
            results!.push(result)
          }
        }
      }
    })

    return results
  }

  _searchLogical(query: Expression): InternalResult[] {
    if (!process.env.LOGICAL_SEARCH_ENABLED) {
      throw new Error(ErrorMsg.LOGICAL_SEARCH_UNAVAILABLE)
    }

    const expression = parse(query, this.options)

    // Keyless leaves fan out across all keys; normalised weights keep their
    // scores consistent with string and keyed queries.
    const keys = this._normalizedKeys()

    const evaluate = (
      node: ParsedNode,
      item: any,
      idx: number
    ): InternalResult[] => {
      if (!('children' in node)) {
        const { keyId, searcher } = node as ParsedLeaf

        let matches: MatchScore[]

View on GitHub (pinned to edf2fb608e)

Solutions

1. Set process.env.LOGICAL_SEARCH_ENABLED to a truthy value before calling search with an object query.
2. Rewrite the query as a plain string pattern if logical operators are not needed.
3. Load dotenv or platform env config early so the flag is present in all environments.

Example fix

// before
fuse.search({ $and: [{ title: 'old' }, { title: 'world' }] })
// after
process.env.LOGICAL_SEARCH_ENABLED = '1'
fuse.search({ $and: [{ title: 'old' }, { title: 'world' }] })

if (typeof query === 'object' && !process.env.LOGICAL_SEARCH_ENABLED) {
  throw new Error('Set LOGICAL_SEARCH_ENABLED to use logical (object) queries')
}
return fuse.search(query)

const logicalSearchReady = () => Boolean(process.env.LOGICAL_SEARCH_ENABLED)

try {
  return fuse.search(query)
} catch (e) {
  if (e.message === 'Logical search is not available') {
    process.env.LOGICAL_SEARCH_ENABLED = '1'
    return fuse.search(query)
  }
  throw e
}

When it happens

Trigger: fuse.search({ $and: [...], $or: [...] }) or any object query routed to _searchLogical while process.env.LOGICAL_SEARCH_ENABLED is unset or falsy at search time.

Common situations: Adopting logical queries after upgrading without knowing about the env gate; the flag set locally but missing in deployed/serverless environments.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Extended search is not available
• Token search is not available
• Invalid value for key ${key}

AI-assisted analysis of krisk/Fuse@edf2fb608e (2026-09-02). Data as JSON: /api/errors/876ff3fa46f9b036. Report an issue: GitHub.