moeru-ai/airi · error · Error

Unknown settings JSON

Error message

Unknown settings JSON

What it means

`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.

Source

Thrown at packages/stage-ui-live2d/src/utils/live2d-zip-loader.ts:138

}

function useArchivePathResolution(settings: ModelSettings): ModelSettings {
  const resolveURL = settings.resolveURL.bind(settings)
  settings.resolveURL = path => normalizeLive2DArchivePath(resolveURL(path))
  return settings
}

function createModelSettings(text: string, url: string): ModelSettings {
  if (!text) {
    throw new Error(`Empty settings file: ${url}`)
  }

  const settingsJSON = JSON.parse(text) as JSONObject & { url?: string }
  settingsJSON.url = url
  const runtime = Live2DFactory.findRuntime(settingsJSON)

  if (!runtime) {
    throw new Error('Unknown settings JSON')
  }

  return useArchivePathResolution(runtime.createModelSettings(settingsJSON))
}

export function isSettingsFile(file: string) {
  return !shouldIgnoreLive2DArchiveEntry(file)
    && !file.endsWith('items_pinned_to_model.json')
    && (file.endsWith('.model3.json') || file.endsWith('.model.json'))
}

export function isMocFile(file: string) {
  return file.endsWith('.moc3')
}

export function basename(path: string): string {
  // https://stackoverflow.com/a/15270931
  return path.split(/[\\/]/).pop()!

View on GitHub (pinned to 27111382b4)

Solutions

1. Confirm the file is a genuine `.model3.json` (Cubism 4) or `.model.json` (Cubism 2) with a top-level `Version` and `FileReferences`.
2. Ensure the settings-file selector (`isSettingsFile`) picked the correct entry, excluding `items_pinned_to_model.json` and non-model JSON.
3. Update the Live2D runtime packages if the Cubism version is newer than supported.
4. Route the file to the correct loader (MMD `.pmx`/`.pmd`, Spine `.skel`+`.atlas`) instead of the Live2D path.

Example fix

// before
const settings = createModelSettings(text, url)  // throws on non-Live2D JSON

// after
const json = JSON.parse(text)
if (!json.Version || !json.FileReferences)
  throw new Error(`${url} is not a recognized Live2D model manifest`)
const settings = createModelSettings(text, url)

const json = JSON.parse(text)
if (!json || typeof json !== 'object' || !('FileReferences' in json) || !('Version' in json))
  throw new Error(`${url} is not a recognized Live2D manifest`)
createModelSettings(text, url)

function looksLikeLive2DManifest(text: string): boolean {
  try {
    const j = JSON.parse(text)
    return !!j && typeof j === 'object' && 'FileReferences' in j
  } catch { return false }
}

try {
  createModelSettings(text, url)
} catch (e) {
  if (e instanceof Error && e.message === 'Unknown settings JSON') {
    // route to correct loader or reject the file
  } else throw e
}

When it happens

Trigger: 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.).

Common situations: 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.

Related errors

• Empty settings file: ${url}
• Expected exactly one moc file, got ${mocFiles.length} ${file
• Textures not found
• Cannot find file: ${path}
• Settings file not found

AI-assisted analysis of moeru-ai/airi@27111382b4 (2026-08-12). Data as JSON: /api/errors/e2173ccb69d670c9. Report an issue: GitHub.