{"record":{"id":"e2173ccb69d670c9","repo":"moeru-ai/airi","slug":"unknown-settings-json","errorCode":null,"errorMessage":"Unknown settings JSON","messagePattern":"Unknown settings JSON","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/stage-ui-live2d/src/utils/live2d-zip-loader.ts","lineNumber":139,"sourceCode":"}\n\nfunction useArchivePathResolution(settings: ModelSettings): ModelSettings {\n  const resolveURL = settings.resolveURL.bind(settings)\n  settings.resolveURL = path => normalizeLive2DArchivePath(resolveURL(path))\n  return settings\n}\n\nfunction createModelSettings(text: string, url: string): ModelSettings {\n  if (!text) {\n    throw new Error(`Empty settings file: ${url}`)\n  }\n\n  const settingsJSON = JSON.parse(text) as JSONObject & { url?: string }\n  settingsJSON.url = url\n  const runtime = Live2DFactory.findRuntime(settingsJSON)\n\n  if (!runtime) {\n    throw new Error('Unknown settings JSON')\n  }\n\n  return useArchivePathResolution(runtime.createModelSettings(settingsJSON))\n}\n\nexport function isSettingsFile(file: string) {\n  return !shouldIgnoreLive2DArchiveEntry(file)\n    && !file.endsWith('items_pinned_to_model.json')\n    && (file.endsWith('.model3.json') || file.endsWith('.model.json'))\n}\n\nexport function isMocFile(file: string) {\n  return file.endsWith('.moc3')\n}\n\nexport function basename(path: string): string {\n  // https://stackoverflow.com/a/15270931\n  return path.split(/[\\\\/]/).pop()!","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/moeru-ai/airi/blob/9c213115f8bd0fff9e6eabab02b077ac32da21be/packages/stage-ui-live2d/src/utils/live2d-zip-loader.ts#L121-L157","documentation":"Thrown by createModelSettings when Live2DFactory.findRuntime(settingsJSON) returns undefined, i.e. pixi-live2d-display could not recognize the parsed JSON as either a Cubism 2 (.model.json) or Cubism 4 (.model3.json) settings document. Recognition is content-based (runtime-sniffing fields like FileReferences/Version/Moc), so a syntactically valid JSON that lacks those markers — a motion3.json, physics, or a hand-written file — is 'unknown'.","triggerScenarios":"Passing a .model3.json whose top-level keys were renamed or stripped; a settings file that is actually a pose/physics/motion JSON misnamed as model3.json; a JSON whose 'Version'/'FileReferences' structure doesn't match what the Cubism4 runtime detector expects; corrupt JSON that parsed to something other than a settings object.","commonSituations":"Renaming exp3.json or other files to .model3.json to satisfy isSettingsFile; editing settings JSON and accidentally changing the case of keys; mixing Cubism2-only fields so neither runtime claims it; tooling that re-serializes JSON and drops fields with falsy values (e.g. deletes Version: 3 treated as removable).","solutions":["Verify the file is a genuine model settings export: it should contain FileReferences (with Moc and Textures) for Cubism 4, or the classic model.json fields for Cubism 2","If content is fine, check that only pixi-live2d-display cubism4/cubism2 runtimes you expect are registered — findRuntime iterates registered runtimes","Re-export the model from the official editor instead of hand-crafting JSON","Catch the error and report the settings URL so the user can inspect that specific file"],"exampleFix":"// before\nconst settings = createModelSettings(text, url) // 'Unknown settings JSON'\n\n// after\nconst json = JSON.parse(text)\nconst looksCubism4 = typeof json.Version === 'number' && json.FileReferences?.Moc\nif (!looksCubism4 && json.model?.textures == null) {\n  throw new Error(`\"${url}\" does not look like a Cubism 2/4 model settings file (missing FileReferences.Moc or model.textures)`) \n}\nconst settings = createModelSettings(text, url)","handlingStrategy":"try-catch","validationCode":"const json = JSON.parse(text)\nconst isCubism4 = typeof json?.Version !== 'undefined' && !!json?.FileReferences?.Moc\nconst isCubism2 = Array.isArray(json?.model?.textures)\nif (!isCubism4 && !isCubism2) throw new Error(`${url} is not a recognized Cubism 2/4 settings document`)","typeGuard":"function looksLikeModelSettings(json: any): boolean {\n  return Boolean(json && (json.FileReferences?.Moc || Array.isArray(json.model?.textures)))\n}","tryCatchPattern":"catch (e) { if (e.message === 'Unknown settings JSON') { showUserError('This settings file is not a Cubism 2/4 model export. Re-export from the official editor.'); return } throw e }","preventionTips":["Only feed genuine editor-exported model3.json/model.json files to the loader","Don't rename motion/physics JSONs to .model3.json","Keep runtime detection libs (pixi-live2d-display cubism2/4) registered"],"tags":["live2d","pixi-live2d-display","runtime-detection","model-settings"],"backgroundTag":"live2d-model-load-failed","analyzedSha":"9c213115f8bd0fff9e6eabab02b077ac32da21be","analyzedAt":"2026-08-18T17:29:58.153Z","contentChangedAt":"2026-08-18T17:29:58.153Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}