The failures that actually happen, across all three clients, and how to clear them.
Ordered roughly by how often they land in a helpdesk queue.
Triage in three questions
Before anything else, establish these. They resolve the large majority of reports on their own:
1
Is the user signed in?
None of the clients do anything at all until the user has authenticated. The desktop agents cannot even enable monitoring while signed out.
2
Is monitoring switched on?
The desktop agents ship with monitoring off by default, every install. A user who never flipped the toggle sees nothing and reasonably concludes the tool is broken.
3
Is the user on a supported surface?
The browser extension only activates on its allow-listed AI sites. Native desktop apps need the desktop agent.
Browser extension
The Analyze affordance never appears
Confirm the site is in the extension’s host permission list — see Browser extension. If the site is supported, check that the extension is enabled for that profile; users with multiple Chrome profiles routinely test in the profile that does not have it.
Signed out repeatedly, or sign-in loops
Token handling lives entirely in the background service worker. Service workers are terminated aggressively by the browser; a network interruption during a refresh can leave a stale token. Signing out and back in clears it. If it recurs across many users, check reachability to your Auth0 tenant from the corporate network.
The extension disappeared after a policy push
A force-install policy replaces a manually installed copy. This is normal, but user settings tied to the old installation may not carry over. Have the user sign in again.
Works in Chrome, not in Edge
They are separate builds from separate store listings. Confirm the Edge build was deployed and that your managed-policy entry uses the Edge Add-ons update URL, not the Chrome Web Store one.
macOS agent
Accessibility is granted but nothing happens
The most common macOS issue by a wide margin. macOS sometimes holds a stale permission record after an app update. Go to System Settings → Privacy & Security → Accessibility, remove PromptShields, add it back, and restart the app. If that fails, restart the Mac to clear the accessibility daemon cache.
The permission prompt never appeared
The prompt is only triggered when the user enables monitoring while signed in. If they are signed out, or never touched the toggle, macOS is never asked. Walk them through the toggle first.
Local history is empty or errors
A missing or rotated local encryption key. Recreating it fixes the error but invalidates all locally encrypted data on that device — local history is lost. Server-side history is unaffected.
The overlay appears in the wrong position
The overlay is placed using geometry reported by the Accessibility API. Applications that draw custom, non-standard text controls can report it inaccurately. Capture the application name and version and report it.
Windows agent
Sign-in window is blank or never opens
The WebView2 Runtime is missing. Auth0 sign-in is hosted in WebView2, so without it users can install but never authenticate. Install the Evergreen Runtime. This is the single most common Windows deployment failure — check it first on any older image.
Sign-in completes but the app never returns
The prompt-shields:// protocol handler was not registered or is blocked by policy. Allow-list the scheme and confirm registration survived your packaging method.
A second instance will not launch
Intended behaviour — a named mutex enforces a single instance. If the app seems gone but will not relaunch, look for an orphaned process in Task Manager and end it.
History is empty on a different machine
The local database lives at %LocalAppData%\PromptShields\promptshields.db, and %LocalAppData% does not roam. Users moving between machines see empty local history on each. Server-side history is unaffected.
No suggestions in one specific application
Some applications draw custom text controls that do not expose a UI Automation text pattern. Report the application and version so coverage can be assessed.
Console and sign-in
not_provisioned when signing in with Microsoft
Expected when self-serve signup is disabled and the user was never provisioned. Invite them into the tenant and retry. See Identity and access.
Redirect URI mismatch
The redirect URI in your Entra app registration must match the configured value exactly — scheme, host, port, and path.
A user signed in but sees almost nothing
Users auto-joined into an existing tenant get the analyst role. Check their role assignment if they expect administrative views.
Coverage gaps
MDM says installed, but the console shows no check-in
The policy applied but the client never phoned home. Usual causes: the device is offline or offboarded, the user never completed sign-in, or on macOS the Accessibility permission was never granted. Work this list from the console’s offline-agents view.
Detections stopped for a group of users
Check whether a policy was auto-demoted by the watchdog — a sustained false-positive rate above your threshold reverts a Strict policy to Guideline, which stops enforcement while continuing to observe. The policy’s History tab records the watchdog as the actor. See Policies.
An AI tool your users rely on is not covered
Coverage on the browser side is an explicit allow-list. Send the domain so it can be evaluated for addition. In the meantime, the desktop agents cover it if the tool is used through a native application.
What to include when you escalate
The more of this you gather up front, the faster it resolves:
Client and version — browser extension, macOS agent, or Windows agent
Operating system and build
The application or site where the problem occurs
Whether the user is signed in, and whether monitoring is enabled
On macOS, the current monitoring state: disabled, enabled, paused, or awaitingPermissions
Whether the device is MDM-enrolled, and whether the client was force-installed
Timestamp of a specific failed attempt, so it can be matched against the activity log
Never include the prompt text in a support ticket. If a detection behaved unexpectedly, describe the category and the shape of the data — “a 16-digit number in a sentence about invoicing” — rather than pasting the real content.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"PromptShields","colors":{"primary":"#2563EB","light":"#60A5FA","dark":"#1D4ED8"},"favicon":"https://mintcdn.com/promptshields-eb2257ab/CD4uhGV_c3IHuNpY/favicon.svg?fit=max\u0026auto=format\u0026n=CD4uhGV_c3IHuNpY\u0026q=85\u0026s=c863cc07871f57f0b9ec8e7604aa7473","navbar":{"primary":{"type":"button","label":"promptshields.com","href":"https://promptshields.com"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"promptshields-eb2257ab","hasAudioNarration":false,"actualSubdomain":"promptshields-eb2257ab","customDomains":["docs.promptshields.com"],"gitSource":{"type":"github","owner":"prompt-shields","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{},"buildId":"6ad52c715ec9dc5442ebe93e","clientVersion":"0.0.4205","searchFilterCounts":[{"language":"default","tag":"PromptShields","count":19},{"language":"default","tag":"AI Vendor Trust Exchange","count":12},{"language":"default","tag":"AI Token Lens","count":8},{"language":"default","tag":"Developers","count":7},{"language":"default","tag":"Agent Sentinel","count":6},{"language":"default","tag":"Administer","count":4},{"language":"default","tag":"Deploy","count":4},{"language":"default","tag":"Overview","count":3},{"language":"default","tag":"Operate","count":1}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"troubleshooting","slug":"/troubleshooting","pageMetadata":{"title":"Troubleshooting","description":"The failures that actually happen, across all three clients, and how to clear them.","icon":"wrench","href":"/troubleshooting"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"The failures that actually happen, across all three clients, and how to clear them.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,em:`em`,li:`li`,p:`p`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{Accordion,AccordionGroup,Heading,Step,Steps,Warning}=_components;if(!Accordion)_missingMdxReference(`Accordion`,true);if(!AccordionGroup)_missingMdxReference(`AccordionGroup`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Step)_missingMdxReference(`Step`,true);if(!Steps)_missingMdxReference(`Steps`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Ordered roughly by how often they land in a helpdesk queue.`}),`\n`,_jsx(Heading,{level:`2`,id:`triage-in-three-questions`,children:`Triage in three questions`}),`\n`,_jsx(_components.p,{children:`Before anything else, establish these. They resolve the large majority of reports on their own:`}),`\n`,_jsxs(Steps,{children:[_jsx(Step,{title:`Is the user signed in?`,children:_jsx(_components.p,{children:`None of the clients do anything at all until the user has authenticated. The desktop agents cannot even enable monitoring while signed out.`})}),_jsx(Step,{title:`Is monitoring switched on?`,children:_jsxs(_components.p,{children:[`The desktop agents ship with monitoring `,_jsx(_components.strong,{children:`off`}),` by default, every install. A user who never flipped the toggle sees nothing and reasonably concludes the tool is broken.`]})}),_jsx(Step,{title:`Is the user on a supported surface?`,children:_jsx(_components.p,{children:`The browser extension only activates on its allow-listed AI sites. Native desktop apps need the desktop agent.`})})]}),`\n`,_jsx(Heading,{level:`2`,id:`browser-extension`,children:`Browser extension`}),`\n`,_jsxs(AccordionGroup,{children:[_jsx(Accordion,{title:`The Analyze affordance never appears`,id:`the-analyze-affordance-never-appears`,children:_jsxs(_components.p,{children:[`Confirm the site is in the extension’s host permission list — see `,_jsx(_components.a,{href:`/deploy/browser-extension`,children:`Browser extension`}),`. If the site is supported, check that the extension is enabled for that profile; users with multiple Chrome profiles routinely test in the profile that does not have it.`]})}),_jsx(Accordion,{title:`Signed out repeatedly, or sign-in loops`,id:`signed-out-repeatedly-or-sign-in-loops`,children:_jsx(_components.p,{children:`Token handling lives entirely in the background service worker. Service workers are terminated aggressively by the browser; a network interruption during a refresh can leave a stale token. Signing out and back in clears it. If it recurs across many users, check reachability to your Auth0 tenant from the corporate network.`})}),_jsx(Accordion,{title:`The extension disappeared after a policy push`,id:`the-extension-disappeared-after-a-policy-push`,children:_jsx(_components.p,{children:`A force-install policy replaces a manually installed copy. This is normal, but user settings tied to the old installation may not carry over. Have the user sign in again.`})}),_jsx(Accordion,{title:`Works in Chrome, not in Edge`,id:`works-in-chrome-not-in-edge`,children:_jsx(_components.p,{children:`They are separate builds from separate store listings. Confirm the Edge build was deployed and that your managed-policy entry uses the Edge Add-ons update URL, not the Chrome Web Store one.`})})]}),`\n`,_jsx(Heading,{level:`2`,id:`macos-agent`,children:`macOS agent`}),`\n`,_jsxs(AccordionGroup,{children:[_jsx(Accordion,{title:`Accessibility is granted but nothing happens`,id:`accessibility-is-granted-but-nothing-happens`,children:_jsxs(_components.p,{children:[`The most common macOS issue by a wide margin. macOS sometimes holds a stale permission record after an app update. Go to `,_jsx(_components.strong,{children:`System Settings → Privacy \u0026 Security → Accessibility`}),`, remove PromptShields, add it back, and restart the app. If that fails, restart the Mac to clear the accessibility daemon cache.`]})}),_jsx(Accordion,{title:`The permission prompt never appeared`,id:`the-permission-prompt-never-appeared`,children:_jsx(_components.p,{children:`The prompt is only triggered when the user enables monitoring while signed in. If they are signed out, or never touched the toggle, macOS is never asked. Walk them through the toggle first.`})}),_jsx(Accordion,{title:`Local history is empty or errors`,id:`local-history-is-empty-or-errors`,children:_jsxs(_components.p,{children:[`A missing or rotated local encryption key. Recreating it fixes the error but `,_jsx(_components.strong,{children:`invalidates all locally encrypted data`}),` on that device — local history is lost. Server-side history is unaffected.`]})}),_jsx(Accordion,{title:`The overlay appears in the wrong position`,id:`the-overlay-appears-in-the-wrong-position`,children:_jsx(_components.p,{children:`The overlay is placed using geometry reported by the Accessibility API. Applications that draw custom, non-standard text controls can report it inaccurately. Capture the application name and version and report it.`})})]}),`\n`,_jsx(Heading,{level:`2`,id:`windows-agent`,children:`Windows agent`}),`\n`,_jsxs(AccordionGroup,{children:[_jsx(Accordion,{title:`Sign-in window is blank or never opens`,id:`sign-in-window-is-blank-or-never-opens`,children:_jsxs(_components.p,{children:[`The `,_jsx(_components.strong,{children:`WebView2 Runtime`}),` is missing. Auth0 sign-in is hosted in WebView2, so without it users can install but never authenticate. Install the Evergreen Runtime. This is the single most common Windows deployment failure — check it first on any older image.`]})}),_jsx(Accordion,{title:`Sign-in completes but the app never returns`,id:`sign-in-completes-but-the-app-never-returns`,children:_jsxs(_components.p,{children:[`The `,_jsx(_components.code,{children:`prompt-shields://`}),` protocol handler was not registered or is blocked by policy. Allow-list the scheme and confirm registration survived your packaging method.`]})}),_jsx(Accordion,{title:`A second instance will not launch`,id:`a-second-instance-will-not-launch`,children:_jsx(_components.p,{children:`Intended behaviour — a named mutex enforces a single instance. If the app seems gone but will not relaunch, look for an orphaned process in Task Manager and end it.`})}),_jsx(Accordion,{title:`History is empty on a different machine`,id:`history-is-empty-on-a-different-machine`,children:_jsxs(_components.p,{children:[`The local database lives at `,_jsx(_components.code,{children:`%LocalAppData%\\\\PromptShields\\\\promptshields.db`}),`, and `,_jsx(_components.code,{children:`%LocalAppData%`}),` does not roam. Users moving between machines see empty local history on each. Server-side history is unaffected.`]})}),_jsx(Accordion,{title:`No suggestions in one specific application`,id:`no-suggestions-in-one-specific-application`,children:_jsx(_components.p,{children:`Some applications draw custom text controls that do not expose a UI Automation text pattern. Report the application and version so coverage can be assessed.`})})]}),`\n`,_jsx(Heading,{level:`2`,id:`console-and-sign-in`,children:`Console and sign-in`}),`\n`,_jsxs(AccordionGroup,{children:[_jsx(Accordion,{title:`not_provisioned when signing in with Microsoft`,id:`not-provisioned-when-signing-in-with-microsoft`,children:_jsxs(_components.p,{children:[`Expected when self-serve signup is disabled and the user was never provisioned. Invite them into the tenant and retry. See `,_jsx(_components.a,{href:`/admin/identity-and-access`,children:`Identity and access`}),`.`]})}),_jsx(Accordion,{title:`Redirect URI mismatch`,id:`redirect-uri-mismatch`,children:_jsx(_components.p,{children:`The redirect URI in your Entra app registration must match the configured value exactly — scheme, host, port, and path.`})}),_jsx(Accordion,{title:`A user signed in but sees almost nothing`,id:`a-user-signed-in-but-sees-almost-nothing`,children:_jsx(_components.p,{children:`Users auto-joined into an existing tenant get the analyst role. Check their role assignment if they expect administrative views.`})})]}),`\n`,_jsx(Heading,{level:`2`,id:`coverage-gaps`,children:`Coverage gaps`}),`\n`,_jsxs(AccordionGroup,{children:[_jsx(Accordion,{title:`MDM says installed, but the console shows no check-in`,id:`mdm-says-installed-but-the-console-shows-no-check-in`,children:_jsx(_components.p,{children:`The policy applied but the client never phoned home. Usual causes: the device is offline or offboarded, the user never completed sign-in, or on macOS the Accessibility permission was never granted. Work this list from the console’s offline-agents view.`})}),_jsx(Accordion,{title:`Detections stopped for a group of users`,id:`detections-stopped-for-a-group-of-users`,children:_jsxs(_components.p,{children:[`Check whether a policy was auto-demoted by the watchdog — a sustained false-positive rate above your threshold reverts a Strict policy to Guideline, which stops enforcement while continuing to observe. The policy’s History tab records the watchdog as the actor. See `,_jsx(_components.a,{href:`/admin/policies`,children:`Policies`}),`.`]})}),_jsx(Accordion,{title:`An AI tool your users rely on is not covered`,id:`an-ai-tool-your-users-rely-on-is-not-covered`,children:_jsx(_components.p,{children:`Coverage on the browser side is an explicit allow-list. Send the domain so it can be evaluated for addition. In the meantime, the desktop agents cover it if the tool is used through a native application.`})})]}),`\n`,_jsx(Heading,{level:`2`,id:`what-to-include-when-you-escalate`,children:`What to include when you escalate`}),`\n`,_jsx(_components.p,{children:`The more of this you gather up front, the faster it resolves:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Client and version — browser extension, macOS agent, or Windows agent`}),`\n`,_jsx(_components.li,{children:`Operating system and build`}),`\n`,_jsx(_components.li,{children:`The application or site where the problem occurs`}),`\n`,_jsx(_components.li,{children:`Whether the user is signed in, and whether monitoring is enabled`}),`\n`,_jsxs(_components.li,{children:[`On macOS, the current monitoring state: `,_jsx(_components.code,{children:`disabled`}),`, `,_jsx(_components.code,{children:`enabled`}),`, `,_jsx(_components.code,{children:`paused`}),`, or `,_jsx(_components.code,{children:`awaitingPermissions`})]}),`\n`,_jsx(_components.li,{children:`Whether the device is MDM-enrolled, and whether the client was force-installed`}),`\n`,_jsx(_components.li,{children:`Timestamp of a specific failed attempt, so it can be matched against the activity log`}),`\n`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`Never include the prompt text in a support ticket. If a detection behaved unexpectedly, describe the `,_jsx(_components.em,{children:`category`}),` and the shape of the data — “a 16-digit number in a sentence about invoicing” — rather than pasting the real content.`]})})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Troubleshooting","description":"The failures that actually happen, across all three clients, and how to clear them.","icon":"wrench","href":"/troubleshooting"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Triage in three questions","slug":"triage-in-three-questions","depth":2,"children":[]},{"title":"Browser extension","slug":"browser-extension","depth":2,"children":[]},{"title":"macOS agent","slug":"macos-agent","depth":2,"children":[]},{"title":"Windows agent","slug":"windows-agent","depth":2,"children":[]},{"title":"Console and sign-in","slug":"console-and-sign-in","depth":2,"children":[]},{"title":"Coverage gaps","slug":"coverage-gaps","depth":2,"children":[]},{"title":"What to include when you escalate","slug":"what-to-include-when-you-escalate","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"promptshields-eb2257ab","siteName":"PromptShields","title":"Troubleshooting - PromptShields","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-08-20T08:21:19.588Z","originalFileLocation":"troubleshooting.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"The failures that actually happen, across all three clients, and how to clear them.\">\u003cmeta data-mint-head name=\"application-name\" content=\"PromptShields\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/promptshields-eb2257ab/p3theFoutP3w3GoL/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/promptshields-eb2257ab/p3theFoutP3w3GoL/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/promptshields-eb2257ab/p3theFoutP3w3GoL/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/promptshields-eb2257ab/p3theFoutP3w3GoL/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/promptshields-eb2257ab/p3theFoutP3w3GoL/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/promptshields-eb2257ab/p3theFoutP3w3GoL/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/promptshields-eb2257ab/p3theFoutP3w3GoL/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/promptshields-eb2257ab/p3theFoutP3w3GoL/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/promptshields-eb2257ab/p3theFoutP3w3GoL/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Troubleshooting - PromptShields\">\u003cmeta data-mint-head property=\"og:description\" content=\"The failures that actually happen, across all three clients, and how to clear them.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"PromptShields\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.promptshields.com/troubleshooting\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://promptshields-eb2257ab.mintlify.site/_mintlify/api/og/v2?division=Operate\u0026amp;title=Troubleshooting\u0026amp;description=The+failures+that+actually+happen%2C+across+all+three+clients%2C+and+how+to+clear+them.\u0026amp;theme=c6b247f82d0b28602e760c10\u0026amp;signature=de83bcfa1731c3926e257a9b990166369d6d0ccef5f5f3612d3c6fc3fb23b6c6\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Troubleshooting - PromptShields\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"The failures that actually happen, across all three clients, and how to clear them.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://promptshields-eb2257ab.mintlify.site/_mintlify/api/og/v2?division=Operate\u0026amp;title=Troubleshooting\u0026amp;description=The+failures+that+actually+happen%2C+across+all+three+clients%2C+and+how+to+clear+them.\u0026amp;theme=c6b247f82d0b28602e760c10\u0026amp;signature=de83bcfa1731c3926e257a9b990166369d6d0ccef5f5f3612d3c6fc3fb23b6c6\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/promptshields-eb2257ab/p3theFoutP3w3GoL/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"PromptShields\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2563EB\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.promptshields.com/troubleshooting\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/troubleshooting.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.promptshields.com/#organization\",\"name\":\"PromptShields\",\"url\":\"https://docs.promptshields.com\"},{\"@type\":\"WebSite\",\"@id\":\"https://docs.promptshields.com#website\",\"name\":\"PromptShields\",\"url\":\"https://docs.promptshields.com\",\"publisher\":{\"@id\":\"https://docs.promptshields.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.promptshields.com/troubleshooting#webpage\",\"url\":\"https://docs.promptshields.com/troubleshooting\",\"name\":\"Troubleshooting\",\"description\":\"The failures that actually happen, across all three clients, and how to clear them.\",\"dateModified\":\"2026-08-20T08:21:19.588Z\",\"isPartOf\":{\"@id\":\"https://docs.promptshields.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.promptshields.com/troubleshooting#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.promptshields.com/troubleshooting#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"PromptShields\",\"item\":\"https://docs.promptshields.com\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Troubleshooting\",\"item\":\"https://docs.promptshields.com/troubleshooting\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.promptshields.com/troubleshooting#article\",\"headline\":\"Troubleshooting\",\"name\":\"Troubleshooting\",\"description\":\"The failures that actually happen, across all three clients, and how to clear them.\",\"url\":\"https://docs.promptshields.com/troubleshooting\",\"mainEntityOfPage\":{\"@id\":\"https://docs.promptshields.com/troubleshooting#webpage\"},\"dateModified\":\"2026-08-20T08:21:19.588Z\",\"publisher\":{\"@id\":\"https://docs.promptshields.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.promptshields.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"PromptShields\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"PromptShields\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/troubleshooting.md","siteName":"PromptShields","nav":{"global":null,"tabs":[{"tab":"PromptShields","groups":[{"group":"Overview","pages":[{"title":"PromptShields for IT","icon":"shield-check","href":"/introduction"},{"title":"How it works","icon":"diagram-project","href":"/how-it-works"},{"title":"Data handling","icon":"lock","href":"/data-handling"}]},{"group":"Deploy","pages":[{"title":"Browser extension","icon":"chrome","href":"/deploy/browser-extension"},{"title":"macOS agent","icon":"apple","href":"/deploy/macos-agent"},{"title":"Windows agent","icon":"windows","href":"/deploy/windows-agent"},{"title":"MDM rollout","icon":"tower-broadcast","href":"/deploy/mdm-rollout"}]},{"group":"Administer","pages":[{"title":"Identity and access","icon":"key","href":"/admin/identity-and-access"},{"title":"Policies","icon":"shield","href":"/admin/policies"},{"title":"Monitoring and reporting","icon":"chart-line","href":"/admin/monitoring-and-reporting"},{"title":"Integrations","icon":"plug","href":"/admin/integrations"}]},{"group":"Developers","pages":[{"title":"Developer overview","icon":"code","href":"/developers/overview"},{"title":"Python SDK","icon":"python","href":"/developers/python-sdk"},{"title":"AI Gateway","icon":"server","href":"/developers/ai-gateway"},{"title":"Self-hosting the collector","icon":"server","href":"/developers/self-host"},{"title":"Registry API","icon":"database","href":"/developers/registry-api"},{"title":"Discovery sources","icon":"radar","href":"/developers/discovery-sources"},{"title":"Confidence scoring","description":"How the registry decides how much to trust each discovered asset.","icon":"gauge-high","href":"/developers/confidence-scoring"}]},{"group":"Operate","pages":[{"title":"Troubleshooting","icon":"wrench","href":"/troubleshooting"}]}]},{"tab":"AI Token Lens","pages":[{"title":"AI Token Lens","href":"/ai-token-lens/introduction"}]},{"tab":"Agent Sentinel","pages":[{"title":"Agent Sentinel","href":"/agent-sentinel/introduction"}]},{"tab":"AI Vendor Trust Exchange","pages":[{"title":"AI Vendor Trust Exchange","href":"/ai-vendor-trust-exchange/introduction"}]}]},"basePath":"","title":"Troubleshooting - PromptShields","deploymentId":"dpl_FZMKUpaaKiVETbfqhoUe4sPFDTmY","buildId":"dpl_FZMKUpaaKiVETbfqhoUe4sPFDTmY","dynamics":[],"chunks":[]}