{"record":{"id":"01bdc160dc23edc1","repo":"naptha/tesseract.js","slug":"initialization-failed","errorCode":null,"errorMessage":"initialization failed","messagePattern":"initialization failed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/worker-script/index.js","lineNumber":305,"sourceCode":"        const debugStr = TessModule.FS.readFile('/debugDev.txt', { encoding: 'utf8', flags: 'a+' });\n        if (dataFromCache && /components are not present/.test(debugStr)) {\n          log('Data from cache missing requested OEM model. Attempting to refresh cache with new language data.');\n          // In this case, language data is re-loaded\n          await loadLanguage({ workerId, payload: { langs: loadLanguageLangsWorker, options: loadLanguageOptionsWorker } }); // eslint-disable-line max-len\n          status = api.Init(null, langs, oem, configFile);\n          if (status === -1) {\n            log('Language data refresh failed.');\n            const delCachePromise2 = langsArr.map((lang) => adapter.deleteCache(`${loadLanguageOptionsWorker.cachePath || '.'}/${lang}.traineddata`));\n            await Promise.all(delCachePromise2);\n          } else {\n            log('Language data refresh successful.');\n          }\n        }\n      }\n    }\n\n    if (status === -1) {\n      res.reject('initialization failed');\n    }\n\n    res.progress({\n      workerId, status: statusText, progress: 1,\n    });\n    res.resolve();\n  } catch (err) {\n    res.reject(err.toString());\n  }\n};\n\n// Combines default output with user-specified options and\n// counts (1) total output formats requested and (2) outputs that require OCR\nconst processOutput = (output) => {\n  const workingOutput = JSON.parse(JSON.stringify(defaultOutput));\n\n  const nonRecOutputs = ['imageColor', 'imageGrey', 'imageBinary', 'layoutBlocks', 'debug'];\n  let recOutputCount = 0;","sourceCodeStart":287,"sourceCodeEnd":323,"githubUrl":"https://github.com/naptha/tesseract.js/blob/a1ca80d9e31c34512d0ded75ff8821ddcf3f2f91/src/worker-script/index.js#L287-L323","documentation":"api.Init(null, langs, oem, configFile) returns -1 when Tesseract cannot initialize with the provided language data and engine mode. The library already attempts one automatic recovery: if cached data triggered the 'components are not present' debug message, it refreshes the cache and retries Init once. If the status is still -1 after that, it rejects with 'initialization failed'.","triggerScenarios":"Corrupted or truncated .traineddata; OEM mismatch such as requesting the legacy engine against LSTM-only language data; invalid/malformed lang string; partial download cached from a previous run; config file syntax error.","commonSituations":"Stale bad data in the cache directory from an interrupted download; using OEM.TESSERACT_ONLY with the default LSTM-only traineddata; custom config string that Tesseract rejects; disk/memory exhaustion during init.","solutions":["Clear the cache (delete the cachePath directory or set cacheMethod: 'refresh' for one run) to force a clean re-download.","Match OEM to the data variant — legacy engine needs the full traineddata, LSTM needs the LSTM build; pass legacyCore/legacyLang consistently.","Verify the lang string format ('+'-separated ISO 639-3 codes) and that every code was actually loaded.","If passing a config object/string, simplify or remove it to isolate the cause."],"exampleFix":"// before\nconst worker = await createWorker('eng', OEM.TESSERACT_ONLY); // LSTM data cached -> init -1\n\n// after\nconst worker = await createWorker('eng', OEM.TESSERACT_ONLY, {\n  legacyCore: true,\n  legacyLang: true,\n  cacheMethod: 'refresh', // force re-download of correct data\n});","handlingStrategy":"fallback","validationCode":"// Ensure OEM and data variant are consistent before init.\nconst OEM = require('tesseract.js').OEM;\nfunction consistentOemData(oem, legacyLang, legacyCore) {\n  const needsLegacy = oem === OEM.TESSERACT_ONLY || oem === OEM.TESSERACT_LSTM_COMBINED;\n  if (needsLegacy && (!legacyLang || !legacyCore)) {\n    throw new Error('Legacy OEM requested without legacyLang/legacyCore');\n  }\n}\nconsistentOemData(OEM.TESSERACT_ONLY, options.legacyLang, options.legacyCore);","typeGuard":"const oemRequiresLegacyData = (oem) =>\n  oem === 0 /* TESSERACT_ONLY */ || oem === 2 /* TESSERACT_LSTM_COMBINED */;","tryCatchPattern":"// On init failure, clear the cache once and retry with refreshed data.\nasync function initOrRefresh(langs, oem, opts) {\n  try {\n    return await createWorker(langs, oem, opts);\n  } catch (e) {\n    if (/initialization failed/i.test(e.message)) {\n      return await createWorker(langs, oem, { ...opts, cacheMethod: 'refresh' });\n    }\n    throw e;\n  }\n}","preventionTips":["Keep OEM, legacyCore, and legacyLang aligned at worker creation; never mix an LSTM-only data cache with a legacy OEM.","Clear the cache directory when upgrading tesseract.js or switching language data variants.","Use cacheMethod: 'refresh' after upgrades to avoid stale corrupted downloads.","Validate any custom config string/object against Tesseract's expected syntax before passing it."],"tags":["initialization","oem","language-data","cache","configuration"],"backgroundTag":null,"analyzedSha":"a1ca80d9e31c34512d0ded75ff8821ddcf3f2f91","analyzedAt":"2026-08-13T04:28:13.744Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}