actualbudget/actual · error

Invalid ${flagName}: "${value}". Expected "true" or "false".

Error message

Invalid ${flagName}: "${value}". Expected "true" or "false".

What it means

parseBoolFlag strictly validates that a CLI flag string is exactly "true" or "false". Any other string throws this error rather than coercing, so flags behave predictably.

Source

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

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 {

View on GitHub (pinned to d4334cb6e6)

Solutions

1. Pass exactly "true" or "false" as the flag value.
2. Use bare boolean flags (e.g. --closed) instead of value forms if supported.
3. Normalize input before calling, e.g. value.trim().toLowerCase(), if you control the caller.

Example fix

// before
actual-cli accounts --closed=1
// after
actual-cli accounts --closed=true

function isValidBoolFlag(value: string): boolean {
  return value === 'true' || value === 'false';
}

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

When it happens

Trigger: Calling parseBoolFlag with values like "True", "1", "yes", or " true" (whitespace) from commands registered by registerAccountsCommand, registerCategoriesCommand, registerCategoryGroupsCommand, or the flag helper.

Common situations: Users passing --closed=1 or --closed=yes on the CLI; shell scripts quoting values oddly; case sensitivity mistakes.

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 an integer.
• 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/712e8ba6439bc975. Report an issue: GitHub.