actualbudget/actual · critical · Error

The environment variable `lootCoreScript` is not defined. Pl

Error message

The environment variable `lootCoreScript` is not defined. Please define it to point to the server bundle.

What it means

`lazyLoadBackend` in the Electron main process refuses to start unless the `lootCoreScript` environment variable points at the compiled loot-core server bundle. It is undefined here, so the app cannot locate the backend to import and throws immediately.

Source

Thrown at packages/desktop-electron/server.ts:7

import { retry as promiseRetry } from './retry';

const BACKEND_IMPORT_MAX_RETRIES = 30;

const lazyLoadBackend = async (isDev: boolean) => {
  if (process.env.lootCoreScript === undefined) {
    throw new Error(
      'The environment variable `lootCoreScript` is not defined. Please define it to point to the server bundle.',
    );
  }

  try {
    // These retries are primarily for dev mode, where we watch for changes in loot-core
    // In a packaged build this should always work the first time.
    const bundle = await promiseRetry(
      async (retry, number) => {
        try {
          return await import(process.env.lootCoreScript!);
        } catch (error) {
          console.info(
            `Loading server bundle: Attempt ${number} of ${BACKEND_IMPORT_MAX_RETRIES}`,
          );

          retry(error);
        }

View on GitHub (pinned to d4334cb6e6)

Solutions

1. Set the `lootCoreScript` env var to the absolute path of the built loot-core server bundle before launching the Electron main process
2. Rebuild the app with the official packaging scripts so the bundle path is injected
3. Check the electron-builder/packaging config to ensure `lootCoreScript` is included in the packaged app's environment

Example fix

// before
yarn electron packages/desktop-electron
// after
lootCoreScript=./packages/loot-core/lib-dist/app.node.js yarn electron packages/desktop-electron

if (typeof process.env.lootCoreScript !== 'string' || !process.env.lootCoreScript) {
  throw new Error('Set lootCoreScript to the loot-core server bundle path before starting electron.');
}
import fs from 'fs';
if (!fs.existsSync(process.env.lootCoreScript)) {
  throw new Error(`lootCoreScript bundle missing at ${process.env.lootCoreScript}; build loot-core first.`);
}

When it happens

Trigger: Launching the packaged Electron app (isDev = false) when the main process was started without `process.env.lootCoreScript` set to the path of the loot-core server bundle.

Common situations: Running the electron binary directly instead of via the build scripts that set the env var; a broken packaging step that failed to emit or reference the server bundle; custom dev harnesses that only set the var in dev mode.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Failed to init the server bundle after all retries: ${String
• ACTUAL_DATA_DIR is not set
• ACTUAL_DATA_DIR env variable is required
• Invalid token_expiration value: ${val}: value was "${val}"
• applyAppUpdate not implemented in electron app

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