{"record":{"id":"30733ac761b33300","repo":"tobi/qmd","slug":"qmd-ast-grammar-unavailable-for-language-m","errorCode":null,"errorMessage":"[qmd] AST grammar unavailable for ${language}: ${message}","messagePattern":"\\[qmd\\] AST grammar unavailable for (.+?): (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/ast.ts","lineNumber":243,"sourceCode":"async function loadGrammar(language: SupportedLanguage): Promise<LanguageType | null> {\n  if (failedLanguages.has(language)) return null;\n\n  const wasmKey = GRAMMAR_MAP[language].wasm;\n  if (!grammarCache.has(wasmKey)) {\n    grammarCache.set(wasmKey, (async () => {\n      const path = resolveGrammarPath(language);\n      return LanguageClass!.load(path);\n    })());\n  }\n\n  try {\n    return await grammarCache.get(wasmKey)!;\n  } catch (err) {\n    failedLanguages.add(language);\n    grammarCache.delete(wasmKey);\n    const message = formatGrammarLoadError(language, err);\n    grammarLoadErrors.set(language, message);\n    console.warn(`[qmd] AST grammar unavailable for ${language}: ${message}`);\n    return null;\n  }\n}\n\n/**\n * Get or create a compiled query for the given language.\n */\nfunction getQuery(language: SupportedLanguage, grammar: LanguageType): QueryType {\n  if (!queryCache.has(language)) {\n    const source = LANGUAGE_QUERIES[language];\n    const query = new QueryClass!(grammar, source);\n    queryCache.set(language, query);\n  }\n  return queryCache.get(language)!;\n}\n\n// =============================================================================\n// AST Break Point Extraction","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/tobi/qmd/blob/dbfd0b4736aeaf761d1a16ca8e424f071df8feb9/src/ast.ts#L225-L261","documentation":"When qmd tries to load a tree-sitter WASM grammar for AST-aware chunking (`--chunk-strategy auto`), loadGrammar caches failures per language: it records the formatted error in grammarLoadErrors, adds the language to failedLanguages, warns '[qmd] AST grammar unavailable for ...' and returns null. Callers then fall back to regex chunking for that language, so indexing continues but without function/class-boundary chunking.","triggerScenarios":"Running indexing with AST chunking enabled for a language whose tree-sitter WASM grammar fails to load — missing/corrupt .wasm file for that language, an unreadable grammars directory, or a grammar compiled for an incompatible tree-sitter version. The catch in loadGrammar (src/ast.ts:243) fires and the warning is emitted once per language.","commonSituations":"A partial install where some grammar .wasm files were not downloaded; upgrading node-llama-cpp/tree-sitter runtime so older WASM grammars are ABI-incompatible; filesystem permissions on the grammars cache; a newly supported language that has no bundled grammar yet.","solutions":["Check the detailed reason via the formatted message in the warning or by querying grammarLoadErrors/failedLanguages from src/ast.ts to identify the exact load failure","Reinstall/refresh the grammar WASM files for the affected language (reinstall the package or clear the grammar cache so it re-downloads)","Keep the default `regex` chunk-strategy if AST chunking is not required — Markdown and unknown types always use regex anyway","If the grammar is incompatible after a dependency upgrade, pin the previous working version of the grammar/runtime package"],"exampleFix":"# before\nqmd collection add . --name docs --chunk-strategy auto   # warns: grammar unavailable\n\n# after (grammars refreshed, or fall back explicitly)\nbun install   # refreshes tree-sitter grammar assets\nqmd collection add . --name docs --chunk-strategy auto\n# or explicitly:\nqmd collection add . --name docs --chunk-strategy regex","handlingStrategy":"fallback","validationCode":"import { grammarLoadErrors, failedLanguages } from './ast'; // conceptual\n\nfunction chunkStrategyFor(ext: string): 'auto' | 'regex' {\n  const astLanguages = new Set(['.ts', '.tsx', '.js', '.py', '.go', '.rs']);\n  return astLanguages.has(ext) ? 'auto' : 'regex';\n}\n// Additionally check grammarLoadErrors after a run; if your language is listed,\n// fall back to --chunk-strategy regex.","typeGuard":"function isAstSupported(ext: string): boolean {\n  return ['.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs'].includes(ext);\n}","tryCatchPattern":null,"preventionTips":["After installs/upgrades, run a small test index with --chunk-strategy auto and check for the grammar-unavailable warning","Keep tree-sitter grammar assets in sync with the runtime (reinstall after upgrading node-llama-cpp)","If a language's grammar is unavailable, index with the default regex strategy — results stay correct, just less precisely chunked"],"tags":["tree-sitter","wasm","grammar","ast-chunking","fallback"],"backgroundTag":"wasm-grammar-load-failure","analyzedSha":"dbfd0b4736aeaf761d1a16ca8e424f071df8feb9","analyzedAt":"2026-08-28T18:07:46.628Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}