actualbudget/actual · error

Invalid : " ". Expected "true", "false", "1", or "0".

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.

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"').

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• Invalid config file: expected an object with keys
• Invalid config file: key
• Invalid config file: key
• Invalid config file: unknown key
• Invalid cutoff date: expected a valid date (e.g…

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

Appendix: 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)