actualbudget/actual · error

Invalid ${flagName}: "${value}". Expected an integer.

Error message

Invalid ${flagName}: "${value}". Expected an integer.

What it means

parseIntFlag parses a CLI flag string into an integer and throws when the value is empty or not an integral number (Number.isInteger fails). It rejects decimals, non-numeric strings, and blank input.

Source

Thrown at packages/cli/src/utils.ts:17

export function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

export function parseBoolFlag(value: string, flagName: string): boolean {
  if (value !== 'true' && value !== 'false') {
    throw new Error(
      `Invalid ${flagName}: "${value}". Expected "true" or "false".`,
    );
  }
  return value === 'true';
}

export function parseIntFlag(value: string, flagName: string): number {
  const parsed = value.trim() === '' ? NaN : Number(value);
  if (!Number.isInteger(parsed)) {
    throw new Error(`Invalid ${flagName}: "${value}". Expected an integer.`);
  }
  return parsed;
}

export function parseNonNegativeIntFlag(
  value: string,
  flagName: string,
): number {
  const parsed = parseIntFlag(value, flagName);
  if (parsed < 0) {
    throw new Error(
      `Invalid ${flagName}: "${value}". Expected a non-negative integer.`,
    );
  }
  return parsed;
}

export function parseBoolEnv(

View on GitHub (pinned to d4334cb6e6)

Solutions

1. Supply a plain integer string, e.g. --limit=50.
2. Remove thousands separators and whitespace from the value.
3. Round or validate user input before passing it to the CLI.

Example fix

// before
actual-cli query --limit=10.5
// after
actual-cli query --limit=10

function isValidIntFlag(value: string): boolean {
  const n = value.trim() === '' ? NaN : Number(value);
  return Number.isInteger(n);
}

let limit: number;
try {
  limit = parseIntFlag(value, '--limit');
} catch (err) {
  console.error((err as Error).message);
  process.exit(1);
}

When it happens

Trigger: Calling parseIntFlag (used by balance/amount query builders via buildQueryFromFlags, e.g. limit/offset flags) with values like "10.5", "abc", "", or "1e3" (1e3 parses to 1000 and would pass, but "1.0" would fail... actually "1.0" -> 1 passes; "10.5" fails).

Common situations: Typing --limit=ten, --offset=2.5, or leaving a flag value empty; locale-formatted numbers with commas like "1,000".

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Invalid ${flagName}: "${value}". Expected "true" or "false".
• Invalid ${flagName}: "${value}". Expected a non-negative int
• Invalid --name: must be a non-empty string.
• No update fields provided. Use --name or --offbudget.
• Invalid cutoff date: expected a valid date (e.g. YYYY-MM-DD)

AI-assisted analysis of actualbudget/actual@d4334cb6e6 (2026-08-29). Data as JSON: /api/errors/0de7189211a1ad86. Report an issue: GitHub.