What causes "Invalid --name: must be a non-empty string." in actualbudget/actual?

Pass a non-empty name: `accounts update --name "Checking"`.

actualbudget/actual · error · Error

Invalid --name: must be a non-empty string.

Error message

Invalid --name: must be a non-empty string.

What it means

The accounts CLI `update` command validates --name before building the update fields. Passing --name with only whitespace (e.g. --name " ") is rejected because an empty name is not a meaningful account update. The CLI throws synchronously in the command action.

Source

Thrown at packages/cli/src/commands/accounts.ts:80

          );
          printOutput({ id }, opts.format);
        },
        { mutates: true },
      );
    });

  accounts
    .command('update <id>')
    .description('Update an account')
    .option('--name <name>', 'New account name')
    .option('--offbudget <bool>', 'Set off-budget status')
    .action(async (id: string, cmdOpts) => {
      const opts = program.opts();
      const fields: Record<string, unknown> = {};
      if (cmdOpts.name !== undefined) {
        const trimmed = cmdOpts.name.trim();
        if (trimmed === '') {
          throw new Error('Invalid --name: must be a non-empty string.');
        }
        fields.name = trimmed;
      }
      if (cmdOpts.offbudget !== undefined) {
        fields.offbudget = parseBoolFlag(cmdOpts.offbudget, '--offbudget');
      }
      if (Object.keys(fields).length === 0) {
        throw new Error(
          'No update fields provided. Use --name or --offbudget.',
        );
      }
      await withConnection(
        opts,
        async () => {
          await api.updateAccount(id, fields);
          printOutput({ success: true, id }, opts.format);
        },
        { mutates: true },

View on GitHub (pinned to d4334cb6e6)

Solutions

Pass a non-empty name: `accounts update <id> --name "Checking"`.
Check the shell variable actually contains a value before invoking the CLI.
If you intended not to rename, omit --name entirely.

Example fix

// before
NAME="   "
actual accounts update abc123 --name "$NAME"
// after
NAME="Checking"
[ -n "$(echo "$NAME" | tr -d '[:space:]')" ] && actual accounts update abc123 --name "$NAME"

Defensive patterns

Strategy: validation

Validate before calling

const name = (process.argv[3] ?? '').trim();
if (!name) {
  console.error('Provide a non-empty --name');
  process.exit(2);
}
// then: accounts update <id> --name "$name"

Type guard

function isNonEmptyString(v: unknown): v is string {
  return typeof v === 'string' && v.trim().length > 0;
}

Try / catch

try {
  await runCli(['accounts', 'update', id, '--name', name]);
} catch (e) {
  if (String(e.message).includes('Invalid --name')) {
    console.error('Account name cannot be blank — supply a real name.');
    process.exitCode = 2;
  } else throw e;
}

Prevention

Trim and check shell variables before interpolating into --name.
Quote all flag values in scripts to avoid whitespace-only args.
Omit --name entirely when not renaming.
Add a preflight non-empty check in batch-update scripts.

When it happens

Trigger: Running `actual-cli accounts update <id> --name " "` (or tabs/whitespace) — the trimmed value is empty so the guard fires.

Common situations: Shell variables that expand to empty or spaces (NAME="$BLANK"); copy-pasted commands with trailing whitespace; scripted batch updates where a CSV field was blank.

Related errors

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