Enterprise Troubleshooting

When a configuration doesn't arrive or doesn't do what you expect, start on the "Information" page of AI Studio on the device in question, then read the log.

The Information page

It shows the state of the device in one sentence:

What it says	Meaning
This is a private AI Studio installation. It runs without an enterprise configuration.	AI Studio found no complete pair of configuration ID and server address. See The device finds no configuration.
… with an enterprise configuration and configuration servers. The configuration plugins are not yet available.	AI Studio knows the configuration but couldn't load it yet. See The configuration isn't loaded.
… The configuration plugins are active.	Everything arrived.
ID mismatch: the plugin ID differs from the enterprise configuration ID.	The ID in your plugin.lua isn't the ID on the device.
A test configuration is active.	Something is staged below .config-tests. It disappears with the next start.

For each configuration, the page also shows its ID, the source where AI Studio found it (registry, policy file, or environment variable), the slot, and whether an encryption secret is configured. The panel "Your Data Folders" shows the folders of AI Studio on this device.

The log

The "Information" page shows the path of the log file events.log, which lies in the data folder of AI Studio. The "Log Viewer" assistant shows and filters it inside the app. Warnings about configurations name the plugin, the setting, and the problem, for example, a value that isn't allowed.

The device finds no configuration

• Windows: the values must be below HKEY_CURRENT_USER\Software\github\MindWork AI Studio\Enterprise IT, of the type REG_SZ, with names in lowercase, and both values of a pair in the same slot, such as config_id_00000 and config_server_url_00000. Check this in the context of the user, not of the administrator.
• Old registry entries hide policy files. AI Studio uses the first source with a complete pair. A pair in the registry, even an outdated one or one with an invalid ID, means AI Studio doesn't look at the policy files.
• Policy files: a single line AI Studio can't read invalidates the whole file. Use whole-line comments only, and exactly the file names config_00000.yaml and so on, in lowercase.
• Linux: when XDG_CONFIG_DIRS is set without /etc/xdg, AI Studio doesn't read /etc/xdg/mindwork-ai-studio/.
• Flatpak: the files belong in the folder of the provisioning extension, with the right architecture and branch, see Deploying on Linux. The sandbox doesn't see /etc/xdg of the host.
• macOS: the only folder is /Library/Application Support/MindWork/AI Studio/.

The configuration isn't loaded

• Can the device reach the server? Open {server address}/{configuration ID}.zip in a browser on the device, with the ID in lowercase. The server must answer with the archive.
• Is the certificate trusted? With a certificate of your own certificate authority, AI Studio must trust it, see Configuration Server. In a Flatpak, this usually needs the policy file for root certificates.
• Does the archive contain a plugin.lua? And does the plugin load? A syntax error in Lua prevents the whole plugin from loading; the log names it.
• Is TYPE = "CONFIGURATION" set?

Changes don't arrive

• AI Studio checks every 16 minutes. Group policies need their own refresh before that.
• Without an ETag from your server, devices receive changes only at their next start.
• A configuration that can't be loaded keeps the previous version active.

A setting doesn't apply

• The name or the value is wrong. The log names settings with values that aren't allowed. Names are case-sensitive.
• Another configuration wins. The one with the higher PRIORITY decides, see How Central Configuration Works.
• A list was replaced. A configuration with a higher priority that sets a list, such as DataApp.HiddenAssistants, replaces it as a whole.
• An empty text doesn't lock a setting that expects an ID, such as DataApp.PreselectedProvider. AI Studio ignores it.
• A preselection is off. Some settings, such as the template of the Slide Assistant or the minimum confidence of the Batch Processing Assistant, apply only while the preselections of that assistant are on. Lock its PreselectOptions to true.
• The device runs an older version that doesn't know the setting yet.

API keys are missing

• The device has no encryption secret, or a different one. The "Information" page shows whether one is configured.
• The key is in the format ENC:v2:, and the device runs a version before v26.10.1. Use ENC:v1: until every device is updated, see Providers and API Keys.
• The secret changed, and the keys weren't exported again with the new secret.
• On Linux, the Secret Service isn't running, or its default collection is locked.

A provider isn't offered

• It is below a minimum confidence that applies, see Confidence and Data Security.
• With a CUSTOM scheme, a provider type you left out gets "Unknown", which is below every minimum.
• It is prohibited by DataApp.ProhibitedProviders.

An assistant plugin isn't approved or enabled

• The approval refers to the hash of the plugin. After any change to its Lua files, the hash changes, and the approval no longer applies. The security card of the plugin shows the current and the approved hash.
• AI Studio honors approvals only from configurations below .config or .config-tests.
• Activate enables only plugins your organization rolled out, see Assistants and Templates.

Still stuck?

Open an issue and describe what the "Information" page shows. Leave out configuration IDs, server addresses, and keys.