actualbudget/actual · error

Error loading data into the spreadsheet.

Error message

Error loading data into the spreadsheet.

What it means

groupBySelections in ReportOptions.ts switches on the report's `groupBy` selection ('Category', 'Group', 'CategoryGroup', 'Payee', 'Account', 'Interval') to pick the list and label used to load report spreadsheet data. The default branch throws this generic error when groupBy holds an unrecognized value. Because the value is typed as plain `string`, TypeScript cannot guarantee validity, so this runtime check reports an invalid report configuration as a data-loading failure.

Source

Thrown at packages/desktop-client/src/components/reports/ReportOptions.ts:444

      break;
    case 'Payee':
      groupByList = payees.map(payee => {
        return { id: payee.id, name: payee.name, hidden: false };
      });
      groupByLabel = 'payee';
      break;
    case 'Account':
      groupByList = accounts.map(account => {
        return { id: account.id, name: account.name, hidden: false };
      });
      groupByLabel = 'account';
      break;
    case 'Interval':
      groupByList = categoryList;
      groupByLabel = 'category';
      break;
    default:
      throw new Error('Error loading data into the spreadsheet.');
  }
  return [groupByList, groupByLabel];
};

View on GitHub (pinned to d4334cb6e6)

Solutions

1. Log the groupBy value at the throw to see the invalid string.
2. Add a case for the missing grouping option (or map it to an existing one) in groupBySelections.
3. Migrate/normalize persisted report configs to current grouping keys before rendering the report.
4. Restrict the groupBy parameter type to the allowed literal union so invalid values fail at compile time.

Example fix

// before
type GroupBy = string;
// after
type GroupBy = 'Category' | 'Group' | 'CategoryGroup' | 'Payee' | 'Account' | 'Interval';
export const groupBySelections = (groupBy: GroupBy, ...) => ...

const VALID_GROUP_BY = ['Category','Group','CategoryGroup','Payee','Account','Interval'];
if (!VALID_GROUP_BY.includes(groupBy)) {
  groupBy = 'Category'; // safe default
}

type GroupBy = 'Category' | 'Group' | 'CategoryGroup' | 'Payee' | 'Account' | 'Interval';
function isGroupBy(v: string): v is GroupBy {
  return ['Category','Group','CategoryGroup','Payee','Account','Interval'].includes(v);
}

try {
  const [list, label] = groupBySelections(groupBy, categories, groups, payees, accounts);
} catch {
  const [list, label] = groupBySelections('Category', categories, groups, payees, accounts);
}

When it happens

Trigger: Calling groupBySelections with a groupBy value outside the handled set — e.g. a persisted report config saved with an old/renamed grouping option ('category' lowercase, 'month', etc.), or custom report code passing a new grouping mode without adding a case here.

Common situations: Restoring report settings from synced prefs or localStorage written by a different app version where grouping keys were renamed; plugins or custom reports passing their own grouping values; case-sensitivity mistakes when constructing the groupBy string.

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

• Unsupported summary type
• Unknown display type: ${String(displayType)}
• Unknown template type: ${String(type satisfies undefined)}
• Unknown display type: ${String(visualType satisfies never)}
• Unknown display type: ${String(type satisfies never)}

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