actualbudget/actual · error · Error

--last and --limit are mutually exclusive

Error message

--last and --limit are mutually exclusive

What it means

`--last` already caps the number of returned rows (it means 'the last N transactions'), so combining it with the generic `--limit` flag is ambiguous. When both are provided the command throws this error instead of guessing which count applies.

Source

Thrown at packages/cli/src/commands/query.ts:155

  }
  if (Array.isArray(parsed.groupBy)) {
    queryObj = queryObj.groupBy(parsed.groupBy);
  }
  return queryObj;
}

function buildQueryFromFlags(cmdOpts: Record<string, string | undefined>) {
  const last = cmdOpts.last ? parseIntFlag(cmdOpts.last, '--last') : undefined;

  if (last !== undefined) {
    if (cmdOpts.table && cmdOpts.table !== 'transactions') {
      throw new Error(
        '--last implies --table transactions. Cannot use with --table ' +
          cmdOpts.table,
      );
    }
    if (cmdOpts.limit) {
      throw new Error('--last and --limit are mutually exclusive');
    }
  }

  const table =
    cmdOpts.table ?? (last !== undefined ? 'transactions' : undefined);
  if (!table) {
    throw new Error('--table is required (or use --file or --last)');
  }

  if (!(table in TABLE_SCHEMA)) {
    throw new Error(
      `Unknown table "${table}". Available tables: ${AVAILABLE_TABLES}`,
    );
  }

  if (cmdOpts.where && cmdOpts.filter) {
    throw new Error('--where and --filter are mutually exclusive');
  }

View on GitHub (pinned to d4334cb6e6)

Solutions

1. Keep only `--last N` (it already limits results).
2. Or use `--limit N` alone with `--table transactions` if you do not need 'most recent' semantics.
3. Ensure scripts do not inject both flags from different sources.

Example fix

// before
actual query --last 30 --limit 10
// after
actual query --last 30

if (last !== undefined && limit !== undefined) {
  throw new Error('choose either --last or --limit, not both');
}

try {
  await cli(['query', ...args]);
} catch (e) {
  if (e.message.includes('--last and --limit are mutually exclusive')) {
    console.error('Remove one of --last / --limit');
  }
}

When it happens

Trigger: Running `actual query --last 30 --limit 10` — both flags present, `--last` having parsed to a valid number.

Common situations: Adding `--limit` to an existing `--last` command to 'narrow' results; composing flags in scripts where one flag comes from a config file and the other from the command line.

Related errors

• --last implies --table transactions. Cannot use with --table
• 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.

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