tobi/qmd · warning

[qmd] AST grammar unavailable for ${language}: ${message}

Error message

[qmd] AST grammar unavailable for ${language}: ${message}

What it means

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.

Source

Thrown at src/ast.ts:243

async function loadGrammar(language: SupportedLanguage): Promise<LanguageType | null> {
  if (failedLanguages.has(language)) return null;

  const wasmKey = GRAMMAR_MAP[language].wasm;
  if (!grammarCache.has(wasmKey)) {
    grammarCache.set(wasmKey, (async () => {
      const path = resolveGrammarPath(language);
      return LanguageClass!.load(path);
    })());
  }

  try {
    return await grammarCache.get(wasmKey)!;
  } catch (err) {
    failedLanguages.add(language);
    grammarCache.delete(wasmKey);
    const message = formatGrammarLoadError(language, err);
    grammarLoadErrors.set(language, message);
    console.warn(`[qmd] AST grammar unavailable for ${language}: ${message}`);
    return null;
  }
}

/**
 * Get or create a compiled query for the given language.
 */
function getQuery(language: SupportedLanguage, grammar: LanguageType): QueryType {
  if (!queryCache.has(language)) {
    const source = LANGUAGE_QUERIES[language];
    const query = new QueryClass!(grammar, source);
    queryCache.set(language, query);
  }
  return queryCache.get(language)!;
}

// =============================================================================
// AST Break Point Extraction

View on GitHub (pinned to dbfd0b4736)

Solutions

1. 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
2. Reinstall/refresh the grammar WASM files for the affected language (reinstall the package or clear the grammar cache so it re-downloads)
3. Keep the default `regex` chunk-strategy if AST chunking is not required — Markdown and unknown types always use regex anyway
4. If the grammar is incompatible after a dependency upgrade, pin the previous working version of the grammar/runtime package

Example fix

# before
qmd collection add . --name docs --chunk-strategy auto   # warns: grammar unavailable

# after (grammars refreshed, or fall back explicitly)
bun install   # refreshes tree-sitter grammar assets
qmd collection add . --name docs --chunk-strategy auto
# or explicitly:
qmd collection add . --name docs --chunk-strategy regex

import { grammarLoadErrors, failedLanguages } from './ast'; // conceptual

function chunkStrategyFor(ext: string): 'auto' | 'regex' {
  const astLanguages = new Set(['.ts', '.tsx', '.js', '.py', '.go', '.rs']);
  return astLanguages.has(ext) ? 'auto' : 'regex';
}
// Additionally check grammarLoadErrors after a run; if your language is listed,
// fall back to --chunk-strategy regex.

function isAstSupported(ext: string): boolean {
  return ['.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs'].includes(ext);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• [qmd] AST parse failed for ${filepath}, falling back to rege
• Reranker unavailable — skipping reranking (${detail}). Use -

AI-assisted analysis of tobi/qmd@dbfd0b4736 (2026-08-28). Data as JSON: /api/errors/30733ac761b33300. Report an issue: GitHub.