{"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":138,"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":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/moeru-ai/airi/blob/27111382b4a79a7e983289d6e983a06af185ed0f/packages/stage-ui-live2d/src/utils/live2d-zip-loader.ts#L120-L156","documentation":"`createModelSettings` runs `Live2DFactory.findRuntime(settingsJSON)` to pick the correct runtime (Cubism 2 vs Cubism 4) from the parsed JSON. If no runtime recognizes the JSON shape, it throws `Unknown settings JSON`. This means the JSON parsed fine but does not match any known Live2D model manifest schema.","triggerScenarios":"Pointing the loader at a JSON that is not a Live2D model manifest (e.g. a `package.json`, an `items_pinned_to_model.json`, a MMD `.json`, or arbitrary JSON); a Cubism version the installed `@cubism-aware` runtimes do not support; a manifest missing the discriminator fields (`Version`, `FileReferences`, etc.).","commonSituations":"The archive contains multiple JSON files and the wrong one was selected as the settings file; a newer/older Cubism export the runtime does not recognize; the user renamed a non-model JSON to `.model3.json`; the file is a Spine or MMD asset loaded through the Live2D path.","solutions":["Confirm the file is a genuine `.model3.json` (Cubism 4) or `.model.json` (Cubism 2) with a top-level `Version` and `FileReferences`.","Ensure the settings-file selector (`isSettingsFile`) picked the correct entry, excluding `items_pinned_to_model.json` and non-model JSON.","Update the Live2D runtime packages if the Cubism version is newer than supported.","Route the file to the correct loader (MMD `.pmx`/`.pmd`, Spine `.skel`+`.atlas`) instead of the Live2D path."],"exampleFix":"// before\nconst settings = createModelSettings(text, url)  // throws on non-Live2D JSON\n\n// after\nconst json = JSON.parse(text)\nif (!json.Version || !json.FileReferences)\n  throw new Error(`${url} is not a recognized Live2D model manifest`)\nconst settings = createModelSettings(text, url)","handlingStrategy":"validation","validationCode":"const json = JSON.parse(text)\nif (!json || typeof json !== 'object' || !('FileReferences' in json) || !('Version' in json))\n  throw new Error(`${url} is not a recognized Live2D manifest`)\ncreateModelSettings(text, url)","typeGuard":"function looksLikeLive2DManifest(text: string): boolean {\n  try {\n    const j = JSON.parse(text)\n    return !!j && typeof j === 'object' && 'FileReferences' in j\n  } catch { return false }\n}","tryCatchPattern":"try {\n  createModelSettings(text, url)\n} catch (e) {\n  if (e instanceof Error && e.message === 'Unknown settings JSON') {\n    // route to correct loader or reject the file\n  } else throw e\n}","preventionTips":["Confirm the file is a genuine .model3.json/.model.json before loading.","Exclude non-model JSON from settings-file selection.","Keep Live2D runtime packages up to date for new Cubism versions."],"tags":["live2d","model-loading","schema","runtime-detection"],"backgroundTag":null,"analyzedSha":"27111382b4a79a7e983289d6e983a06af185ed0f","analyzedAt":"2026-08-12T18:33:34.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}