Configuration Override Warnings

When you save a setting on a Settings tab, Athena writes it to the server's saved-settings file, appsettings.local.json. But configuration is layered: an environment variable or a command-line argument can supply the same setting at a higher priority — and that source always wins. When it does, your save still reports success but the value the server actually uses does not change. To stop that being invisible, Athena appends a plain-language warning to the save result naming exactly which settings were not really changed and where they come from. This page explains when that warning appears, how to read it from the console, the REST API and scripts, and how to make your change stick.

Why a save can quietly do nothing#

Athena reads its configuration from several sources, layered in order. The last source that supplies a given key wins. From lowest to highest priority:

1. the shipped appsettings.json defaults, and any environment-specific overlay file such as appsettings.Production.json;
2. appsettings.local.json in the server's data directory, which is the file the Settings tabs write to (/data/athena/appsettings.local.json on the virtual appliance);
3. secrets.json in the same directory, which holds only per-install secrets the server generates itself;
4. environment variables, commonly set by a service unit;
5. command-line arguments passed when the server process starts.

When you save on a Settings tab, Athena updates appsettings.local.json. Because that file sits above the shipped and overlay files, a saved value always beats them. If an environment variable or command-line argument also defines that key, though, the write is correct but ineffective: the higher layer still supplies the value the server uses. This is a deliberate and useful feature: overriding by environment lets you pin secrets and environment-specific values outside the file. The override warning does not change who wins; it simply makes the loss visible so you are never misled into thinking a change took effect when it did not.

Which settings tabs it covers#

The override check runs whenever you save one of the following settings groups. Each has its own Save action in the console and its own REST endpoint:

Saving requires the Admin role (the settings.manage permission). The Database tab is read-only, so it has no save and no override warning. For the individual settings on each of these tabs, see General Settings, Security Settings, Agent Settings, and Scheduler Settings.

What the warning looks like#

A normal save returns a short success message, for example “Security settings updated successfully”. When one or more of the values you saved are owned by a higher-priority source, Athena appends a warning that names the count, lists each affected setting with its current effective value and the source it comes from, and tells you what to do. The message follows this shape:

Security settings updated successfully. WARNING: 1 setting(s) were NOT changed
because a higher-priority configuration source supplies them:
Security:MaxFailedLoginAttempts (currently 100000, from an environment variable).
Change them at that source, or remove them from it.

The parts of that warning:

• The count — how many settings in this save were overridden.
• Each setting — its fully qualified key (section and name, e.g. Security:MaxFailedLoginAttempts).
• Its current value — the value the server is actually using right now, not the value you just tried to save. Long values are shortened; an unset value shows as (not set) and a blank one as (empty).
• The source — where that value comes from. Athena walks the layers from highest priority down and reports the winning one, so you are always sent to the right place. The two that most often surprise people are named explicitly: “an environment variable” and “a command-line argument”, since neither is visible in any file on disk. Any other source that is a file is named by its file name.

If several settings are overridden, each is listed, separated by semicolons. Settings that were not overridden in the same save are applied normally — the warning never blocks the rest of the payload.

In the console#

When you save on a Settings tab in the browser, the warning is shown alongside the success confirmation, so you see immediately which values did not take effect. No extra step is needed — just read the confirmation that appears after Save.

Reading it over the REST API#

The override warning is delivered in the message field of the standard API response. On a successful save the response has success: true and the message carries any warning text. A script must therefore check message, not just the HTTP status or the success flag — a 200 OK with success: true can still contain a WARNING:.

PUT /api/settings/security
Authorization: Bearer <token>
Content-Type: application/json

{ "maxFailedLoginAttempts": 5 }

Response when a higher-priority source owns the value:

{
  "success": true,
  "message": "Security settings updated successfully. WARNING: 1 setting(s) were NOT changed because a higher-priority configuration source supplies them: Security:MaxFailedLoginAttempts (currently 100000, from an environment variable). Change them at that source, or remove them from it.",
  "data": null
}

A defensive check in a script is simply: after a settings save, if the response message contains WARNING:, treat the affected settings as unchanged and surface the message to whoever ran the automation.

From PowerShell#

Set-AthenaSettings saves a settings category (General, Security, Agent, Scheduler, or Logging) by calling the same endpoints above, so the same override rules apply.

Set-AthenaSettings -Category Security -Settings @{ MaxFailedLoginAttempts = 5 }

The cmdlet prints a generic confirmation line after a successful save. Because a higher-priority source can still be winning, treat a settings change as truly applied only after you read the value back and confirm it matches what you set:

Set-AthenaSettings -Category Security -Settings @{ MaxFailedLoginAttempts = 5 }
(Get-AthenaSettings -Category Security).MaxFailedLoginAttempts   # expect 5

If the value you read back is not the value you saved, a higher-priority source owns it — check the server's environment variables and command-line arguments, then change or remove the setting there. Set-AthenaSettings also supports -WhatIf and -Confirm so you can preview or gate the change in a script. See the PowerShell Module reference for details.

Making your change take effect#

When a setting is overridden, the fix is always to change it at the winning source — the same source the warning names — or to remove it from there so the value saved in appsettings.local.json can win again:

• An environment variable — update or unset it wherever the server process gets its environment (for example the service unit), then restart the server so the new environment is read. Remember the double-underscore naming, e.g. Security__MaxFailedLoginAttempts.
• A command-line argument — edit the arguments passed to the server process at startup, then restart.

Environment-specific overlay files such as appsettings.Production.json sit below appsettings.local.json, so they no longer override a value you save in the console.

After making the fix, save again (or read the value back) and confirm the warning is gone and the effective value now matches what you intended.

Related#

• Configuration — the full precedence order and the environment-variable naming convention.
• General Settings, Security Settings, Agent Settings, Scheduler Settings — the individual settings on each tab that this check covers.
• Settings Sync — replicating settings to other servers, where the effective (post-override) value is what propagates.
• PowerShell Module — Set-AthenaSettings and Get-AthenaSettings.
• Roles & Permissions — the Admin role required to change settings.