siyuan-note/siyuan · warning

Tesseract OCR is not installed or configured, please refer t

Error message

Tesseract OCR is not installed or configured, please refer to the User Guide - Assets section for configuration

What it means

OcrAsset short-circuits with this localized error when the package-level TesseractEnabled flag is false. The flag is set during boot only if the tesseract binary (TesseractBin) is found on PATH and OCR is enabled in config. Calling OCR on any asset before that is a no-op that returns this error.

Source

Thrown at kernel/util/ocr.go:162

	assetsTextsLock.Lock()
	oldText, ok := assetsTexts[asset]
	assetsTexts[asset] = text
	assetsTextsLock.Unlock()
	if !ok || oldText != text {
		assetsTextsChanged.Store(true)
	}
}

func ExistsAssetText(asset string) (ret bool) {
	assetsTextsLock.Lock()
	_, ret = assetsTexts[asset]
	assetsTextsLock.Unlock()
	return
}

func OcrAsset(asset string) (ret []map[string]any, err error) {
	if !TesseractEnabled {
		err = errors.New(Langs[Lang][266])
		return
	}

	assetsPath := GetDataAssetsAbsPath()
	assetAbsPath := strings.TrimPrefix(asset, "assets")
	assetAbsPath = filepath.Join(assetsPath, assetAbsPath)
	ret = Tesseract(assetAbsPath)
	assetsTextsLock.Lock()
	ocrText := GetOcrJsonText(ret)
	assetsTexts[asset] = ocrText
	assetsTextsLock.Unlock()
	if "" != ocrText {
		assetsTextsChanged.Store(true)
	}
	return
}

func GetAssetText(asset string) (ret string) {

View on GitHub (pinned to 251596fc0d)

Solutions

1. Install Tesseract (apt-get install tesseract-ocr / brew install tesseract / Windows installer) plus the needed language packs.
2. Ensure 'tesseract' is on PATH, or set TesseractBin to its absolute path.
3. Enable OCR in settings and restart the kernel so TesseractEnabled flips on.
4. If OCR is optional, check TesseractEnabled and degrade gracefully (skip asset indexing).

Example fix

// before
res, err := util.OcrAsset(asset)

// after
if !util.TesseractEnabled {
    logging.LogInfof("OCR disabled, skipping %s", asset)
    return nil
}
res, err := util.OcrAsset(asset)

if !util.TesseractEnabled {
    return nil // OCR unavailable, skip
}
res, err := util.OcrAsset(asset)

func OcrAvailable() bool { return util.TesseractEnabled }

When it happens

Trigger: Invoking OcrAsset (index-time OCR, asset-text search) on a deployment where Tesseract is not installed, not on PATH, disabled in settings, or where the binary name differs from TesseractBin.

Common situations: Fresh install without OCR deps; portable build on a machine without tesseract; OCR toggled off in settings; Docker image without the tesseract package and language data.

Related errors

• copy unused asset [%s] to history failed: %w
• remove unused asset [%s] failed: %w
• parse svg failed: %w
• image attachment request limit exceeded: at most %d images a
• invalid frontend capability ID: %s

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/3395b2273e49c92f. Report an issue: GitHub.