When a configuration file is invalid

Profinity checks its settings files, profiles, rules, collections, derived tags, and menu layouts when it loads them, and this page lists what it does with an invalid one and how to recover. For config.yaml and security.yaml, the two files that control how Profinity is secured and exposed, Profinity stops and shows a message. For the other settings files it carries on with a default and tells you in the log.

What happens to each file

File	If the file is invalid	What changes on disk
`config.yaml`	Profinity does not start and shows a message that names the file and the reason.	Nothing. The file is left exactly as it is.
`security.yaml`	Profinity does not start and shows a message that names the file and the reason.	Nothing. No keys or users are created or changed.
`profile.yaml`	Profinity creates a new default profile, makes it the active profile, and writes the reason to the log.	Nothing in the invalid profile, which is left exactly as it is. The new default profile is saved to disk, and `config.yaml` is updated to name it as the active profile.
`plugins.yaml`	Profinity starts with no registered plugins. Plugin folders it finds are registered as disabled until the file is repaired.	Nothing. Profinity leaves the damaged file as it is.
`theme.yaml`	Profinity starts with the default theme.	Nothing.
`custom.yaml`	Because the file is invalid, the install is not offered the 14-day local trial, so with no licence installed Profinity runs in restricted mode. The component groups that the file hides are shown. Profinity never changes `custom.yaml`, which an original equipment manufacturer (OEM) build supplies, so ask the supplier for a corrected copy.	Nothing.

A file that does not exist counts as valid. Profinity creates the default for config.yaml, security.yaml, and plugins.yaml, and uses the default theme and no custom settings for the others. config.yaml, security.yaml, plugins.yaml, and custom.yaml are in the config folder of the artefacts directory, theme.yaml is in the themes folder, and profile.yaml is in the profile folder. custom.yaml holds the installer settings of an OEM build, such as the trial and the component groups it hides.

Rules, collections, and derived tags

These documents hold many separate items, so Profinity checks each item on its own and keeps running. An item that is not valid is skipped, and every other item still works. A skipped rule is inactive, and a skipped collection or derived tag is withheld.

An item is skipped when it fails its own checks, refers to something missing, or has an unrecognised key, such as a misspelt setting name. Because an item with an unknown key is skipped, check these documents after an upgrade from 2.2. This is a precaution, not a required step, because Profinity keeps running and marks each skipped item. Refer to the breaking changes for what changed.

Profinity writes one line to the log for each skipped item, with the name of the item and the reason. The rules, collections, and derived tags editors show the same list.

Each skipped item has a red Invalid marker, and the reason appears when you point at it. A key that is not inside any item appears in a banner instead of on an item. The file itself stays unchanged when it loads.

To fix a skipped item, open its editor, correct the item named in the marker, and select SAVE. The editors are under TAG UTILITIES in the side menu: RULES & ACTIONS for rules, COLLECTIONS for tag collections, and DERIVED TAGS for derived tags. Saving needs every item in the document to be valid first.

If the whole file cannot be read, the editor tells you so and shows a message in place of an empty list that you might save over the top of it.

A menu layout that is invalid is ignored, and every component appears in its default group. A layout is invalid when it has a mistake such as a misspelt key, a component listed twice, or a value of the wrong type, or when it uses an older format. Profinity writes one message to the log that names the problem, and the profile file is not changed.

The Menu Layout editor shows a notice that gives the reasons. Saving from the editor replaces the ignored layout. Refer to Menu Layout for how to arrange groups and components in the editor.

Profiles

A profile is invalid when it has an unrecognised key at its own level, such as a misspelt setting name, or when it cannot be read as YAML. Profinity checks the profile when it starts. If the profile is invalid, Profinity creates a new default profile and makes it the active profile, and the log names the profile and the reason.

The invalid profile file stays unchanged, so everything in it is kept. To go back to it, correct the key that the log names, then select the profile again in the Profile pill on the ADMIN page, as described in Manage profiles. If the profile named in config.yaml has no profile.yaml, as on a new installation, Profinity treats the profile as missing. It creates a default profile, makes it active, and logs that no profile of that name was found.

Settings inside a component are defined by the component, so Profinity does not check them this way. When Profinity saves the profile, it discards an unrecognised setting for that component. A profile is read only from profile.yaml in the profile folder.

Alert state

Profinity keeps the current state of each alert, including which alerts are acknowledged or silenced, in active_alerts.yaml in the profile's events folder. If that file is damaged or empty, Profinity discards it and rebuilds it from the daily alert files, alerts_<date>.yaml, which hold every alert event. Acknowledged and silenced alerts stay acknowledged and silenced, and the log records the rebuild. A daily file that cannot be read is left out of the rebuild.

What counts as invalid

A settings file is invalid when any of these is true:

The file is empty, or its contents cannot be read as settings.
A value has the wrong type or shape.
The file has a key that Profinity does not define, such as a misspelt setting name.
The file refers to an environment variable, such as ${PROFINITY_ADMIN_USERNAME}, that is not set.

Profinity ignores the keys that 2.2 wrote to config.yaml and that 2.3 dropped, such as mcp, enableScripting, urls, and webSite, so a config.yaml that 2.2 wrote still starts. Any other key that Profinity 2.3 does not define still makes the file invalid.

Recover when Profinity will not start

The message appears in the console, in the Windows desktop start-up dialog, and in the log. It names the file and the reason.

Resetting security.yaml removes users and keys

Deleting security.yaml resets security. All users, roles, and keys are reset, and Profinity creates the default admin account, which must change its password at first sign-in. Values that were encrypted under the old key, such as the AI key and two-factor secrets, become unreadable and must be entered again. Restore the safety copy first if you have one.

Open the file named in the message and fix the problem it reports. theme.yaml is in the themes folder and profile.yaml is in the profile folder; the others are in the config folder of the artefacts directory. If it names a key, correct or remove that key.
If you cannot fix the file, copy it to a safe place so that its content is kept. Then restore the last good copy by copying <file>.bak over it. For example, copy config.yaml.bak over config.yaml.
If both fail, copy the file to a safe place if you have not already, then delete it to reset it. Profinity creates the default on the next start, so a deleted config.yaml returns every setting to its default. Keep custom.yaml, because the OEM build supplies it, and ask your supplier for a corrected copy.
Start Profinity again.

Troubleshooting

What you see	Cause	What to do
Profinity does not start, and the message names an environment variable	The file refers to an environment variable that is not set.	Set the variable and start Profinity again. The file itself is intact, so keep it.
Profinity does not start, and the message says the file could not be read	The account that runs Profinity cannot read the file, or the disk reported an error.	Check the artefacts folder as the account that runs Profinity, and give that account read access to the file, as described in Artefacts directory.
Profinity does not start, and the message names a key or a value	The file has a key that Profinity does not define, or a value of the wrong type.	Follow Recover when Profinity will not start.
A different profile is active after a restart, and the log names your profile	Your profile has an unrecognised key or cannot be read, so Profinity started a default profile.	Correct the key that the log names, then activate your profile again, as described in Profiles.
A rule, collection, or derived tag shows a red Invalid marker	The item fails its checks or has an unknown key, so Profinity skips it.	Point at the marker to read the reason, correct the item in its editor, and select SAVE.
Every component is in its default menu group	The menu layout is invalid, so Profinity ignores it.	Read the notice in the Menu Layout editor, then save the layout from the editor.

The safety copy

Every time Profinity saves one of these files it keeps the version it replaced as <file>.bak, for example config.yaml.bak. Profinity keeps one copy per file, and each save replaces it. A file that is damaged is never copied over the safety copy, so the copy always holds the last file that worked.

The safety copy can hold credentials that you have since removed, so Profinity creates it readable only by the account that runs Profinity. Exported profile packs do not include safety copies, and importing a pack ignores any it contains.

Containers and services

A container that restarts automatically will restart again and again while a file is invalid, and each attempt writes the same message to the log. Read the message, then correct or restore the file in the data volume, and the next start succeeds.

To check the configuration without starting Profinity, run the Profinity console program with --preflight-only. On Windows that program is Profinity-Console.exe, not Profinity.exe, which is the desktop application and does not accept the flag. The installer does not add either program to PATH, so run Profinity-Console.exe from the folder that contains it. The same flag works on the other platforms:

Profinity --preflight-only

The command checks the runtime, config.yaml, and security.yaml, and writes nothing. It reports the runtime checks first, then each invalid file with its message, and exits with code 2. When every check passes, it prints this line and exits with code 0:

[profinity] Preflight checks passed.

Profinity records each user's last sign-in time in a small separate file, user_activity.yaml, beside security.yaml, so signing in does not rewrite security.yaml. If that file is damaged, Profinity ignores it and last sign-in times start again.