siyuan-note/siyuan · warning

Tesseract OCR is not installed or configured, please refer…

Error message

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

What it means

OcrAsset performs OCR on an asset file using the external Tesseract binary. SiYuan gates this behind the TesseractEnabled flag (populated from configuration/environment detection); when it is false the call fails immediately with this localized message rather than attempting to spawn a missing binary.

Solutions

1. Install Tesseract OCR (apt install tesseract-ocr / brew install tesseract / Windows installer)
2. Configure the Tesseract path in Settings - Assets (配置路径) so SiYuan detects it and sets TesseractEnabled
3. Restart the kernel after installing/configuring so detection re-runs
4. In Docker, use an image or Dockerfile layer that includes tesseract-ocr and required language packs

Example fix

// before
// TesseractEnabled == false -> OcrAsset returns i18n error
// after
# install and register the binary
apt-get install -y tesseract-ocr
# set the path in Settings - Assets, restart kernel

// Go
if !util.TesseractEnabled {
    // skip OCR-dependent indexing or prompt the user to configure Tesseract
}

if _, err := util.OcrAsset(asset); err != nil {
    if !util.TesseractEnabled {
        log.Println("OCR unavailable: install/configure Tesseract")
        return nil // degrade gracefully: index without OCR text
    }
    return err
}

When it happens

Trigger: Calling OcrAsset (directly or via the ocr pipeline used by asset full-text indexing / search) while Tesseract OCR is not installed, or its path is not configured in Settings - Assets so TesseractEnabled stays false.

Common situations: Fresh SiYuan installs without Tesseract; Docker images lacking the tesseract-ocr package; users who installed Tesseract but did not set its path in the settings so detection failed.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Langs[Lang][266]
• 346
• 348
• 349
• access to private/internal IP is prohibited

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/3395b2273e49c92f. Report an issue: GitHub.

Appendix: 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 8641553a1f)