> ## Documentation Index
> Fetch the complete documentation index at: https://docs.promptguard.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common Shadow AI failure modes and how to fix them — traffic not intercepted, browser QUIC/HTTP-3 bypass, cert-pinned apps, engine unreachable, and collecting logs for support.

Most issues come down to one of a handful of causes. Start with `pgshadow status`,
then work down this list.

## Traffic isn't being intercepted

If prompts pass through with no verdicts showing up, the agent isn't seeing the
traffic. Check, in order:

<Steps>
  <Step title="Confirm the agent is running and healthy">
    ```bash theme={"system"}
    pgshadow status
    ```

    This reports whether the proxy is up, the certificate is trusted, and the
    engine is reachable. `pgshadow doctor` runs the same checks with more detail.
  </Step>

  <Step title="Confirm the proxy is applied">
    The PAC proxy must be set where your traffic actually flows. Turning
    protection off and back on in the app re-applies both the proxy and the
    certificate trust — that's the quickest fix on every platform. To check by
    hand:

    <Tabs>
      <Tab title="macOS">
        The proxy is set per network service (Wi-Fi vs. Ethernet vs. VPN), and
        switching networks can leave a service uncovered. Check **System
        Settings → Network →** your service **→ Details… → Proxies** for the
        automatic proxy configuration.
      </Tab>

      <Tab title="Windows">
        The proxy is a per-user automatic configuration script. Check
        **Settings → Network & internet → Proxy** (or **Internet Options →
        Connections → LAN settings**) for the setup script.
      </Tab>

      <Tab title="Linux">
        The agent configures the GNOME proxy (`gsettings`: mode `auto` plus the
        autoconfig URL). On desktops without GNOME settings, automatic proxy
        configuration isn't applied — you'll need to point your browser or
        environment at the proxy manually.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Confirm the CA is trusted">
    If TLS interception fails, the browser or app will error or fall back.

    <Tabs>
      <Tab title="macOS">
        Make sure the **PromptGuard** CA is present and trusted in **Keychain
        Access**.
      </Tab>

      <Tab title="Windows">
        The CA is trusted for the **current user** (not machine-wide). Open
        `certmgr.msc` → **Trusted Root Certification Authorities → Certificates**
        and look for the agent's CA.
      </Tab>

      <Tab title="Linux">
        Browser trust (Chrome/Chromium) uses the shared NSS database at
        `~/.pki/nssdb`, which requires `libnss3-tools` (`certutil`) to be
        installed. System-wide trust (`update-ca-certificates`) is only applied
        when the agent runs as root.
      </Tab>
    </Tabs>

    Re-running the app's **Turn on protection** flow (or `pgshadow init`)
    re-trusts the certificate on all platforms.
  </Step>
</Steps>

## Gemini / Chrome traffic slips past

Chrome and some Google properties (including Gemini) prefer **QUIC / HTTP-3**,
which runs over UDP and can route around the HTTP proxy entirely — so that
traffic is never inspected.

**Fix:** disable QUIC via browser policy. In a managed fleet, push a policy that
turns off the experimental QUIC protocol (for Chrome, the `QuicAllowed=false`
enterprise policy). With QUIC off, the browser falls back to HTTPS over the
proxy and inspection resumes.

## A specific app is never inspected

Some native desktop apps **pin their own certificate** and reject the agent's CA
outright. These bypass any inspection proxy and are **out of scope by design** —
this is not a misconfiguration. See
[Known Limitations](/shadow-ai/known-limitations) for the full list and the
coverage policy.

## The engine is unreachable

The agent calls a remote `/guard` engine for each verdict. If it can't reach the
engine, it **waits up to 8 seconds, then fails open** — the request is allowed
through rather than blocking the employee's work.

* A short spike of allowed-without-verdict events during a network blip is
  expected, not a bug.
* If it's persistent, check connectivity to the engine (`pgshadow status` /
  `pgshadow doctor`) and, for self-hosted deployments, that the engine instance
  is healthy. See [Deployment Modes](/shadow-ai/deployment-modes).

<Note>
  Fail-open is the shipping behavior: availability of AI tools is preserved during
  an outage. If your environment requires fail-closed, contact
  [support@promptguard.co](mailto:support@promptguard.co) to discuss options.
</Note>

## SmartScreen blocks the Windows installer

The Windows build is **early access** and the installer is not yet code-signed,
so on first run SmartScreen shows *"Windows protected your PC."* This is
expected: click **More info → Run anyway**.

Before you do, verify the installer's **SHA-256 checksum** against the value
published with the release:

```powershell theme={"system"}
Get-FileHash .\PromptGuard.Shadow_x64-setup.exe -Algorithm SHA256
```

If the hash doesn't match the published value, don't run it — re-download from
[promptguard.co/download](https://promptguard.co/download) and contact
[support@promptguard.co](mailto:support@promptguard.co).

## Where logs and config live

The agent keeps its state in one directory on every platform:

| Platform          | Location                      |
| ----------------- | ----------------------------- |
| **macOS / Linux** | `~/.promptguard/`             |
| **Windows**       | `%USERPROFILE%\.promptguard\` |

Inside it: `config.json` (credentials — never share this file),
`pgshadow-proxy.log` (the proxy log, useful for support), and `events.db` (the
local, PII-redacted event log).

## Collecting logs for support

When you open a ticket, include the output of:

```bash theme={"system"}
pgshadow status
pgshadow doctor
```

These report proxy, certificate, and engine health without exposing prompt
content — the local event log is PII-redacted. Attach `pgshadow-proxy.log` from
the directory above if asked (never `config.json` — it holds your device
credential). Send it all to
[support@promptguard.co](mailto:support@promptguard.co).

## Next steps

<CardGroup cols={2}>
  <Card title="Known limitations" icon="triangle-exclamation" href="/shadow-ai/known-limitations">
    What's out of scope and why.
  </Card>

  <Card title="Privacy & data handling" icon="shield-halved" href="/shadow-ai/privacy-data-handling">
    What the agent logs and what reaches the cloud.
  </Card>
</CardGroup>