Troubleshoot managed settings

Use this guide when a managed setting doesn't apply or Glean Tau blocks agent work. Start with the source and error, then correct the policy or the device condition that caused the failure.

Identify the failure

Different failures need different repairs. Use the following table to choose the next check.

Symptom	Check	Next action
A preference has the wrong value	Higher-priority device sources and whether the setting permits admin control	Correct the source that supplies the effective value
Full access is unavailable	Allowed modes in every security policy	Keep an allowed mode or ask the admin to change policy
A feature is unavailable	Whether policy allows the feature, its on or off preference, platform support, and operating-system permissions	Identify which control prevents use
Managed security policy is unavailable	Source health, enrollment, document format, and file or registry protection	Restore valid policy through the original channel
Policy is unsupported	Required sandbox, proxy, and feature compatibility	Use a supported device and feature set
Work stops after a network outage	Server policy acceptance time and authentication	Restore connectivity or authentication and obtain a valid refresh
Work stops after editing user settings	Errors in ~/.glean/ui/settings.json	Correct the file in Settings → Agent access → Open settings.json

Don't erase chats, clear all app storage, remove enrollment records, or grant broader operating-system permissions to resolve an unidentified policy failure.

Check the delivered source

On macOS, confirm whether policy comes from a user profile, device profile, or protected file. Check both managed preference channels when both exist. A correction to the device profile doesn't remove a restriction in the user profile.

Use these read-only commands to check a local file's syntax and protection:

plutil -convert json -o /dev/null -- /etc/glean/managed-settings.json
ls -lde /etc/glean /etc/glean/managed-settings.json

Exit status 0 means the file is valid JSON. The check doesn't validate Glean setting names, source permissions, or enforcement on the device. Don't use plutil -lint, which rejects every JSON file. An ACL can grant write access even when Unix mode bits appear correct.

For profiles, verify desktopSettings under com.glean.desktop. Other valid app preferences may be present beside it. Use MDM to repair the assigned payload rather than delete generated preference files.

On Windows, verify the machine key, registry view, ownership, and ACLs. See Deploy machine policy. On either platform, a user-owned file or registry value doesn't become administrator policy because its contents look valid.

Check policy content

Confirm the following before you redeploy:

• The app release supports the document format and every setting
• The document uses one version field and has no duplicate keys
• Approval and sandbox limits are in settings["core.authority.requirements"], not under permissions
• Each allowlist in core.authority.requirements is nonempty, and the approval policy and reviewer lists put the preferred fallback first
• Key names in core.authority.requirements are spelled exactly. A near-miss such as allowedSandboxMode blocks the policy, and the reviewer value is auto-review, not auto_review
• Every denyRead path is absolute or starts with ~/, and has no .. segments or glob patterns
• Network restrictions target a supported Mac with the managed proxy
• Enrolled devices receive both features and settings["core.authority.requirements"]
• Every allowed feature supports the managed proxy when the policy requires it

Correct invalid security settings rather than remove them to make the app start. For an unsupported feature, choose a compatible workflow or deliberately revise the policy through your organization's change process.

Verify recovery

After correction, deliver a complete valid replacement through the original source. Confirm that the app accepts it, then test a permitted task and a denied task.

If a server response failed, verify the active account and obtain a valid response. An app restart doesn't clear required device policy. If a valid replacement doesn't restore operation, record the error and contact Glean support.

Changes can invalidate pending approvals. Ask users to retry the affected action after policy health is restored. Don't reuse an old approval as proof that the new operation is permitted.

To remove policy or enrollment instead of repairing it, see Remove managed policy.

Collect information for support

Record the details needed to reproduce the failure:

• App version, operating system, and device architecture
• Time of the failure and the exact visible message
• Delivery source and whether policy is optional or required
• Last successful policy update, if known
• Expected and observed behavior for one allowed and one denied operation
• Whether the issue follows an account change, app upgrade, or policy update

If the Debug feature is available, its Managed configs view can help inspect source and effective configuration. Full debug exports can include raw values and local paths. Review and redact them before sharing. Don't include passwords, access tokens, or unrelated customer data.

See also

• Glean Tau configuration reference — every policy field, default, and example