ramensoftware/windhawk · error

Invalid object array schema definition.

Error message

Invalid object array schema definition.

What it means

describeSetting() detects an object-array schema via isInitialSettingsCollection, which inspects the first element as the row template. If that first entry is an empty array (zero columns/fields), there is no template to derive ObjectArray children from, so the converter throws.

Solutions

1. Ensure the first array entry defines at least one field/column for the object rows
2. Remove the empty object-array definition entirely if the table is unused
3. Check that isInitialSettingsCollection's contract (first element = template) is satisfied by your data

Example fix

// before
describeSetting([[]])
// after
describeSetting([[{ id: 'name', type: 'string' }]])

const isObjectArraySchema = (v: unknown): boolean =>
  Array.isArray(v) && Array.isArray(v[0]) && (v[0] as unknown[]).length > 0;
if (!isObjectArraySchema(raw)) throw new Error('object array needs a non-empty template row');

const hasTemplateRow = (v: unknown[]): v is [unknown[], ...unknown[][]] =>
  Array.isArray(v[0]) && v[0].length > 0;

try { desc = describeSetting(value); } catch (e) { if (e.message.includes('Invalid object array schema')) return null; throw e; }

When it happens

Trigger: Passing an array of arrays whose first element is `[]`, e.g. `[[ ]]`, to describeSetting through descriptor/schemaDescriptor/dataDescriptor when parsing an object-array settings definition.

Common situations: A mod's settings table is declared but all column definitions were removed; an export tool serializes an empty header row.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Initial settings arrays must contain at least one template…
• Unknown setting type for value
• Missing settings key
• Mod id must be specified in the source code
• archive is too large

AI-assisted analysis of ramensoftware/windhawk@61d99ed8e1 (2026-09-12). Data as JSON: /api/errors/cb1fb3c99c189d3c. Report an issue: GitHub.

Appendix: source

Thrown at src/windhawk-frontend/apps/windhawk-frontend/src/app/panel/mod-details/tabs/settings/core/yamlConverter.ts:189

  if (typeof value === 'number') {
    return { kind: SettingType.Number, value, defaultValue: 0 };
  }

  if (typeof value === 'string') {
    return { kind: SettingType.String, value, defaultValue: '' };
  }

  if (!Array.isArray(value) || value.length === 0) {
    throw new Error('Initial settings arrays must contain at least one template entry.');
  }

  const arrayValue: unknown[] = value;

  if (isInitialSettingsCollection(arrayValue)) {
    const [first] = arrayValue;
    if (first.length === 0) {
      throw new Error('Invalid object array schema definition.');
    }
    return { kind: SettingType.ObjectArray, value: arrayValue, children: first };
  }

  if (isInitialSettingsArray(arrayValue)) {
    return { kind: SettingType.NestedObject, value: arrayValue, children: arrayValue };
  }

  if (isNumberArrayValue(arrayValue)) {
    return { kind: SettingType.NumberArray, value: arrayValue, defaultValue: 0 };
  }

  if (isStringArrayValue(arrayValue)) {
    return { kind: SettingType.StringArray, value: arrayValue, defaultValue: '' };
  }

  throw new Error(`Unknown setting type for value: ${JSON.stringify(value)}`);
}

View on GitHub (pinned to 61d99ed8e1)