actualbudget/actual · error

Invalid ${source}: "${raw}". Expected "true", "false", "1",

Error message

Invalid ${source}: "${raw}". Expected "true", "false", "1", or "0".

What it means

parseBoolEnv parses an environment variable into a boolean, accepting "1", "0", and case-insensitive "true"/"false". Any other non-undefined value throws this error listing the accepted forms.

Source

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

): 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(
  raw: string | undefined,
  source: string,
): boolean | undefined {
  if (raw === undefined) return undefined;
  const lower = raw.toLowerCase();
  if (raw === '1' || lower === 'true') return true;
  if (raw === '0' || lower === 'false') return false;
  throw new Error(
    `Invalid ${source}: "${raw}". Expected "true", "false", "1", or "0".`,
  );
}

View on GitHub (pinned to d4334cb6e6)

Solutions

1. Set the variable to 1, 0, true, or false.
2. Unset the variable entirely if you want the default behavior.
3. Clean .env files of quotes, whitespace, and Windows line endings (\r).

Example fix

// before
export ACTUAL_NO_LOCK=yes
// after
export ACTUAL_NO_LOCK=1

function isValidBoolEnv(raw: string | undefined): boolean {
  if (raw === undefined) return true;
  const lower = raw.toLowerCase();
  return raw === '1' || raw === '0' || lower === 'true' || lower === 'false';
}

let noLock: boolean | undefined;
try {
  noLock = parseBoolEnv(process.env.ACTUAL_NO_LOCK, 'ACTUAL_NO_LOCK');
} catch (err) {
  console.error((err as Error).message);
  process.exit(1);
}

When it happens

Trigger: The noLock-related env variable is set to something like "yes", "on", "enabled", or " TRUE " (with whitespace); undefined returns undefined without error.

Common situations: Users exporting VARIABLE=yes in shell profiles; CI config using on/off; trailing whitespace or quotes from .env files ("true\r" or '"true"').

Related errors

• 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)
• No update fields provided. Use --name or --hidden.
• No update fields provided. Use --name or --hidden.

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