actualbudget/actual · error · Error

--table is required (or use --file or --last)

Error message

--table is required (or use --file or --last)

What it means

The `query` command needs to know which table to query. If neither `--table` was given nor a `--file` with a `"table"` field was used nor `--last` (which implies transactions), `buildQueryFromFlags` throws this error telling you the three ways to supply one.

Source

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

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');
  }

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

  let queryObj = api.q(table);

View on GitHub (pinned to d4334cb6e6)

Solutions

1. Add `--table transactions` (or another valid table such as accounts, categories, payees).
2. Or use `--last N` to query the most recent transactions.
3. Or use `--file q.json` where the JSON contains a `"table"` field.

Example fix

// before
actual query --where "amount > 0"
// after
actual query --table transactions --where "amount > 0"

if (!table && !file && last === undefined) {
  throw new Error('query needs --table, --file, or --last');
}

try {
  await cli(['query', ...args]);
} catch (e) {
  if (e.message.includes('--table is required')) {
    console.error('Add --table <name>, --file <q.json>, or --last <n>');
  }
}

When it happens

Trigger: Running `actual query` bare, or with only filter/select flags like `--where "amount > 0"`, with no `--table`, `--file`, or `--last`.

Common situations: First-time users typing `actual query --where ...` expecting a default table; scripts dropping the table argument from a templated command.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• No fields to update. Use --name to specify a new name.
• No valid payee IDs provided in --ids. Provide comma-separate
• --order-by contains an empty field
• Invalid order field in "${trimmed}". Field name cannot be em
• Invalid order direction "${direction}" for field "${field}".

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