actualbudget/actual · error · Error

Invalid order direction "${direction}" for field "${field}".

Error message

Invalid order direction "${direction}" for field "${field}". Expected "asc" or "desc".

What it means

When an `--order-by` segment uses the `field:direction` form, the direction after the colon must be exactly `asc` or `desc`. Anything else (including mixed case, misspellings, or a missing direction like `date:`) is rejected with this error.

Source

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

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

// TODO: Import schema from API once it exposes table/field metadata
const TABLE_SCHEMA: Record<
  string,
  Record<string, { type: string; ref?: string }>
> = {
  transactions: {
    id: { type: 'id' },
    account: { type: 'id', ref: 'accounts' },
    date: { type: 'date' },
    amount: { type: 'integer' },
    payee: { type: 'id', ref: 'payees' },

View on GitHub (pinned to d4334cb6e6)

Solutions

1. Use lowercase `asc` or `desc`: `--order-by date:desc`.
2. Drop the colon and direction entirely for default ascending order: `--order-by date`.
3. Normalize/uppercase-to-lowercase any direction sourced from variables before passing it.

Example fix

// before
actual pay --order-by "date:DESC"
// after
actual pay --order-by "date:desc"

if (direction !== undefined && direction !== 'asc' && direction !== 'desc') {
  throw new Error(`direction must be "asc" or "desc", got "${direction}"`);
}

try {
  await cli(['query', '--table', t, '--order-by', `${field}:${direction}`]);
} catch (e) {
  if (e.message.includes('Invalid order direction')) {
    console.error('Use lowercase asc or desc');
  }
}

When it happens

Trigger: Passing `--order-by "date:ascending"`, `--order-by "date:DESC"`, or `--order-by "date:"` — any post-colon value other than the literal lowercase `asc` or `desc`.

Common situations: Muscle-memory from SQL (`ORDER BY date ASC` spelled out as `ascending`); uppercase direction from environment variables; forgotten direction after the colon.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• --order-by contains an empty field
• Invalid order field in "${trimmed}". Field name cannot be em
• --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/5689b6a56426c296. Report an issue: GitHub.