> For the complete documentation index, see [llms.txt](https://docs.xygeni.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xygeni.io/xygeni-products/xygeni-shield/troubleshooting.md).

# Troubleshooting

### A package I need is blocked

Check why with `xygeni-fw test <ecosystem> <package> <version>`. The `Action:` line ends with what blocked it:

* **`malware_db`**: the version is known to be malicious; the `Reason:` line includes the advisory ID. Use another version. If you believe it is a false positive, contact your security team.
* **`min_age`**: the version is newer than your minimum-age policy allows. Use an older version, wait until it is old enough, or ask for an exception in the **Always allow** list (see [Minimum-age policy](https://docs.xygeni.io/xygeni-products/xygeni-shield/protection-policy.md#minimum-age-policy)).
* **`deny_package`**, **`deny_pattern`** or **`deny_default`**: your organization's Black/White list. `xygeni-fw policy show` shows the rules in force. On a centrally managed machine, ask whoever manages the policy in the dashboard.

On a centrally managed machine, `xygeni-fw policy status` shows whether the latest change made in the dashboard has arrived, and `xygeni-fw policy sync` fetches it at once.

### Nothing is blocked

* Run `xygeni-fw status`. If `Account:` says `NOT ENROLLED` or `NOT ACTIVE`, or `License:` says `DORMANT`, Shield is not protecting the machine: see [Activating Shield](https://docs.xygeni.io/xygeni-products/xygeni-shield/activating.md#checking-the-activation-state).
* If the status shows a `Bypass: WARNING` line, some program is passing through without inspection because it does not trust the Shield certificate. See [Tools that do not trust the Shield certificate](https://docs.xygeni.io/xygeni-products/xygeni-shield/everyday-use.md#tools-that-do-not-trust-the-shield-certificate).
* Shield only inspects the registries listed in [System requirements](https://docs.xygeni.io/xygeni-products/xygeni-shield/requirements.md#network-access). For your own registry mirrors, add them to `monitored_domains` (see [Agent settings](https://docs.xygeni.io/xygeni-products/xygeni-shield/agent-settings.md)).

### My token is refused, or Shield says "NOT ACTIVE"

The token needs the *Xygeni Shield agent* permission, and only personal tokens can have it. Create a new personal token with that permission (see [Creating the token](https://docs.xygeni.io/xygeni-products/xygeni-shield/activating.md#creating-the-token)) and set it with `xygeni-fw config token <token>` or the tray app. Shield becomes active again within seconds, without a restart.

If `xygeni-fw status` shows `Token: WILL STOP WORKING after <date>`, the token works for now but lacks the permission: replace it before that date.

### A tool fails with a certificate error

Run `sudo xygeni-fw trust sync` to add the Shield certificate to the Java, Node.js, pip and git trust stores, and `xygeni-fw trust status` to check them. For other tools, point them to the Shield certificate: `/var/lib/xygeni-fw/ca-cert.pem` on Linux, `C:\ProgramData\Xygeni\Shield\data\ca-cert.pem` on Windows.

### The tray app shows "permission denied" (Linux)

Your user must be in the `xygeni-fw` group, and group changes only take effect at login:

```bash
groups | grep xygeni-fw            # are you in the group?
sudo usermod -aG xygeni-fw "$USER" # add yourself if not
```

Then log out and log back in.

### The tray icon is grey

Shield is not protecting the machine. The first line of the tray menu says why: no token, a token without the Shield permission, no Shield seat available, or the service is stopped. Start the service with `sudo systemctl start xygeni-fw` on Linux or `Start-Service XygeniShield` on Windows.

### Tools cannot connect after Shield stopped

When Shield stops, even unexpectedly, it removes its network settings so that traffic flows directly. If something was left behind (for example, after a forced shutdown), clear it and open a new terminal:

```bash
sudo xygeni-fw system-proxy restore
sudo xygeni-fw system-proxy status      # should say: absent
```

### The malicious packages database is not updating

`xygeni-fw malware status` shows when it was last updated and the last error. Check that the machine can reach `apipmd.xygeni.io` over HTTPS (or your on-premises URL, see `xygeni-fw config show`), and force an update with `sudo xygeni-fw malware sync`. While the database is out of date, the rest of the policy keeps working.

### Logs

* Linux: `sudo journalctl -u xygeni-fw -f`, or `/var/log/xygeni-fw/agent.log`.
* Windows: `C:\ProgramData\Xygeni\Shield\logs\agent.log`.

Every block is logged as a `BLOCKED package=... version=... reason=...` line.

### Getting help

When you contact Xygeni support, include the output of `xygeni-fw status` and the recent lines of the agent log.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.xygeni.io/xygeni-products/xygeni-shield/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
