What causes "${label} is required." in koala73/worldmonitor?

Supply a finite non-negative number for every required quantity field before parsing.

${label} is required.

Error message

${label} is required.

What it means

The quantity() helper in operational-balance.ts throws "${label} is required." when a numeric worksheet field is '', null, or undefined. Required quantity fields must be present before range/precision checks run.

Solutions

Supply a finite non-negative number for every required quantity field before parsing.
Coerce empty form inputs at the boundary: convert '' to undefined only after deciding a default, or reject the form client-side.
Add per-field required checks in the UI before submitting the worksheet.

Example fix

// before
parseOperationalInput({ operation: 'op', unit: 'kg', initialStock: '' });
// after
parseOperationalInput({ operation: 'op', unit: 'kg', initialStock: 0 });

Defensive patterns

Strategy: validation

Validate before calling

const REQUIRED_QTYS = ['initialStock']; // plus any other required quantity fields
for (const f of REQUIRED_QTYS) {
  const v = (payload as any)?.[f];
  if (v === '' || v === null || v === undefined) throw new Error(`${f} is required`);
}

Type guard

const hasQuantity = (w: Record<string, unknown>, f: string): w is Record<string, unknown> & Record<typeof f, number> =>
  w[f] !== undefined && w[f] !== null && w[f] !== '';

Try / catch

try {
  const input = parseOperationalInput(raw);
} catch (e) {
  if (e instanceof Error && e.message.endsWith('is required.')) {
    console.error('Missing required quantity field:', e.message);
  } else throw e;
}

Prevention

Mark quantity inputs as required in the form UI.
Convert empty-string form values to explicit defaults or reject client-side.
For spreadsheet imports, map blank cells to a validation error, not null.
List all required quantity fields in API docs and validate at the boundary.

When it happens

Trigger: Omitting a required quantity field from the worksheet object, or explicitly sending null/'' — e.g. parseOperationalInput({ ..., initialStock: null }) or a form leaving a quantity input empty.

Common situations: HTML forms submitting empty strings for untouched number inputs; partial API updates dropping required fields; spreadsheet imports with blank cells mapped straight into the worksheet object.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

AI-assisted analysis of koala73/worldmonitor@7d06c8633d (2026-09-15). Data as JSON: /api/errors/02b255e96e6c6468. Report an issue: GitHub.

Appendix: source

Thrown at src/utils/operational-balance.ts:15

import type { OperationalBalance, OperationalDelivery, OperationalInput, OperationalSnapshot } from '@/types/operational-balance';

export const MAX_OPERATIONAL_DAYS = 90;
export const MAX_OPERATIONAL_DELIVERIES = 30;
export const MAX_OPERATIONAL_JSON_BYTES = 65_536;
const DAY_MS = 86_400_000;
const round = (value: number) => Math.round(value * 1e6) / 1e6;
const dateAt = (start: string, offset: number) => new Date(Date.parse(start) + offset * DAY_MS).toISOString().slice(0, 10);

function record(value: unknown): Record<string, unknown> {
  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Expected a worksheet object.');
  return value as Record<string, unknown>;
}
function quantity(value: unknown, label: string): number {
  if (value === '' || value === null || value === undefined) throw new Error(`${label} is required.`);
  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1e6 || round(value) !== value) {
    throw new Error(`${label} must be between 0 and 1 million with at most 6 decimal places.`);
  }
  return value;
}
function date(value: unknown): string {
  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value) || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString().slice(0, 10) !== value || value < '1900-01-01' || value > '9998-12-31') {
    throw new Error('Use a valid date from 1900 through 9998.');
  }
  return value;
}

export function parseOperationalInput(value: unknown): OperationalInput {
  const input = record(value);
  if (typeof input.operation !== 'string' || !input.operation.trim() || input.operation.length > 100) throw new Error('Enter an operation name of 1-100 characters.');
  if (typeof input.unit !== 'string' || !/^[\p{L}\p{N} %./-]{1,24}$/u.test(input.unit) || !input.unit.trim()) throw new Error('Enter one quantity unit of 1-24 characters.');
  const unit = input.unit.trim();
  const startDate = date(input.startDate);

View on GitHub (pinned to 7d06c8633d)