actualbudget/actual · error · Error

--order-by contains an empty field

Error message

--order-by contains an empty field

What it means

`parseOrderBy` splits the `--order-by` value on commas and each comma-separated part must name a field. An empty segment (from a leading/trailing/double comma) throws this error, because an empty field name cannot be translated into an `order_by` query expression.

Source

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

import * as api from '@actual-app/api';
import type { Command } from 'commander';

import { withConnection } from '#connection';
import { readJsonInput } from '#input';
import { printOutput } from '#output';
import { isRecord, parseIntFlag } from '#utils';

/**
 * Parse order-by strings like "date:desc,amount:asc,id" into
 * AQL orderBy format: [{ date: 'desc' }, { amount: 'asc' }, 'id']
 */
export function parseOrderBy(
  input: string,
): Array<string | Record<string, string>> {
  return input.split(',').map(part => {
    const trimmed = part.trim();
    if (!trimmed) {
      throw new Error('--order-by contains an empty field');
    }
    const colonIndex = trimmed.indexOf(':');
    if (colonIndex === -1) {
      return trimmed;
    }
    const field = trimmed.slice(0, colonIndex).trim();
    if (!field) {
      throw new Error(
        `Invalid order field in "${trimmed}". Field name cannot be empty.`,
      );
    }
    const direction = trimmed.slice(colonIndex + 1);
    if (direction !== 'asc' && direction !== 'desc') {
      throw new Error(
        `Invalid order direction "${direction}" for field "${field}". Expected "asc" or "desc".`,
      );
    }
    return { [field]: direction };

View on GitHub (pinned to d4334cb6e6)

Solutions

1. Remove empty segments and stray commas: `--order-by date` or `--order-by date:desc,amount`.
2. If assembling the list programmatically, filter out empty strings before joining with commas.

Example fix

// before
actual pay --order-by "date,"
// after
actual pay --order-by "date"

const parts = orderByStr.split(',').map(s => s.trim()).filter(Boolean);
if (parts.length === 0) throw new Error('--order-by must name at least one field');

try {
  await cli(['query', '--table', t, '--order-by', orderByStr]);
} catch (e) {
  if (e.message.includes('--order-by contains an empty field')) {
    console.error('Remove empty segments/stray commas from --order-by');
  }
}

When it happens

Trigger: Passing `--order-by ""`, `--order-by ",date"`, `--order-by "date,"` or `--order-by "date,,amount"` — any input that yields an empty segment after splitting on commas and trimming.

Common situations: Building the flag from a joined list in a script where the last element is empty (`"date,"` from `join(',', [...ids, ''])`); accidental trailing commas when hand-editing commands.

Related errors

• Invalid order field in "${trimmed}". Field name cannot be em
• Invalid order direction "${direction}" for field "${field}".
• --table is required when the input file lacks a "table" fiel
• --table is required (or use --file or --last)
• Unknown table "${table}". Available tables: ${AVAILABLE_TABL

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