{"record":{"id":"fa7e582e4bfb4b2b","repo":"actualbudget/actual","slug":"server-url-is-required-set-server-url-actual-s","errorCode":null,"errorMessage":"Server URL is required. Set --server-url, ACTUAL_SERVER_URL env var, or serverUrl in config file.","messagePattern":"Server URL is required\\. Set --server-url, ACTUAL_SERVER_URL env var, or serverUrl in config file\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/config.ts","lineNumber":181,"sourceCode":"    process.env.ACTUAL_SESSION_TOKEN ??\n    fileConfig.sessionToken;\n\n  const syncId =\n    cliOpts.syncId ?? process.env.ACTUAL_SYNC_ID ?? fileConfig.syncId;\n\n  const dataDir =\n    cliOpts.dataDir ??\n    process.env.ACTUAL_DATA_DIR ??\n    fileConfig.dataDir ??\n    join(homedir(), '.actual-cli', 'data');\n\n  const encryptionPassword =\n    cliOpts.encryptionPassword ??\n    process.env.ACTUAL_ENCRYPTION_PASSWORD ??\n    fileConfig.encryptionPassword;\n\n  if (!serverUrl) {\n    throw new Error(\n      'Server URL is required. Set --server-url, ACTUAL_SERVER_URL env var, or serverUrl in config file.',\n    );\n  }\n\n  if (!password && !sessionToken) {\n    throw new Error(\n      'Authentication required. Set --password/--session-token, ACTUAL_PASSWORD/ACTUAL_SESSION_TOKEN env var, or password/sessionToken in config file.',\n    );\n  }\n\n  const cacheTtl = validateNonNegativeInt(\n    cliOpts.cacheTtl ??\n      parseNonNegativeIntEnv(\n        process.env.ACTUAL_CACHE_TTL,\n        'ACTUAL_CACHE_TTL',\n      ) ??\n      fileConfig.cacheTtl ??\n      60,","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/actualbudget/actual/blob/d4334cb6e6123f4d3bcea1ad6166608884c7e658/packages/cli/src/config.ts#L163-L199","documentation":"resolveConfig merges CLI options, environment variables, and the config file, and requires a server URL to establish any connection. When none of --server-url, ACTUAL_SERVER_URL, or config file serverUrl is set, it throws this error before any network call is made.","triggerScenarios":"Running any command that calls config()/resolveConfig with no --server-url flag, no ACTUAL_SERVER_URL env var, and no serverUrl key in the config file.","commonSituations":"Fresh CI setup where only ACTUAL_PASSWORD was exported; forgetting the config file lives in a different directory than expected so it is never read; switching from the desktop app to CLI where the URL was previously implicit.","solutions":["Pass --server-url=https://your-actual-server (or the appropriate flag for the command).","Export ACTUAL_SERVER_URL in your shell/CI environment.","Add \"serverUrl\": \"https://your-actual-server\" to the config file.","Verify the config file you edited is the one being loaded (check the config path resolution)."],"exampleFix":"// before (CI env)\nACTUAL_PASSWORD=secret\n// after\nACTUAL_PASSWORD=secret\nACTUAL_SERVER_URL=https://actual.example.com","handlingStrategy":"validation","validationCode":"const serverUrl = cliOpts.serverUrl ?? process.env.ACTUAL_SERVER_URL ?? fileConfig.serverUrl;\nif (!serverUrl) {\n  throw new Error('Server URL is required. Set --server-url, ACTUAL_SERVER_URL, or serverUrl in config file.');\n}","typeGuard":"function hasServerUrl(o: { serverUrl?: string }): o is { serverUrl: string } & typeof o {\n  return typeof o.serverUrl === 'string' && o.serverUrl.length > 0;\n}","tryCatchPattern":"try {\n  const config = await config(opts);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Server URL is required')) {\n    console.error('Set ACTUAL_SERVER_URL or pass --server-url.');\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Set ACTUAL_SERVER_URL once in your shell profile or CI environment variables.","Keep a checked-in example config (config.example.json) with serverUrl filled.","Validate required env vars at job startup in CI (fail fast with a clear message).","Confirm the config file path the CLI loads before assuming it was read."],"tags":["config","cli","env","missing-option"],"backgroundTag":"missing-env-var","analyzedSha":"d4334cb6e6123f4d3bcea1ad6166608884c7e658","analyzedAt":"2026-08-29T01:02:11.213Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}