Troubleshooting

Server fails to start because the BigFix CA is missing

Example symptom:

failed to read BigFix CA certificate: open <path>: no such file or directory

Verify that bigfix.ca_cert_path resolves from the configured workspace, contains the approved PEM certificate or CA bundle, and is readable by the service account. Restart the service after you correct the path or permissions.

MCP client reports TypeError: fetch failed

Common causes are:

• The service is not listening on port 9495.
• The listener certificate is not trusted by the environment running the MCP client.
• The client URL hostname or IP does not match a certificate SAN.
• A firewall blocks client-to-server traffic.

Check the listener, verify the certificate SAN, install trust in the environment running the client, and restart the client. For remote development environments, trust must exist where the MCP extension host runs.

Authentication fails

Verify that:

• The client sends the complete Authorization: Bearer <token> header.
• The token is valid for the configured BigFix Server.
• bigfix.url uses HTTPS and production port 52315.
• The MCP host can reach the BigFix REST API.
• The configured CA validates the certificate presented by BigFix.

Repeated authentication failures can lock the source IP for lockout_duration_seconds. Wait for the lockout to expire after you correct the credentials or connection.

Remediate entitlement denial

If authentication succeeds but the user does not satisfy the embedded entitlement policy, the server returns 403 Forbidden and reports that the tool is available only with a Remediate license.

Verify that:

• The authenticated BigFix user has an active Remediate entitlement.
• The client is connected to the intended BigFix Server configured by bigfix.url.
• The bearer token belongs to the intended user and has not expired.

An entitlement denial does not count as a failed credential attempt and does not trigger the authentication lockout counter.

Tools are missing

Run MCP: List Servers and inspect the server output. Confirm that the server is connected and the BigFix token was supplied. Restart the MCP client entry after you change its configuration.

The expected tool names are:

get_cve_patch_data
fetch_patch_files
generate_fixlet

Vendor certificate pin mismatch

A pin mismatch causes the vendor connection to fail closed. Confirm system time and ordinary CA trust first. Do not disable TLS validation or replace the embedded policy at runtime.

Vendor certificate rotations require a newly built and signed server binary containing reviewed SHA3-256 SPKI pins. Install the approved update or escalate the failure to the product maintainer with the hostname, timestamp, server version, and redacted log entry.

Patch lookup returns multiple products or files

This can be a valid vendor response. Refine the CVE, KB, catalog query, architecture, channel, package identifier, or version. Review product names and classifications rather than selecting the first result automatically.

Fixlet generation rejects missing SHA-1

Microsoft KB/MSU flows require SHA-1 because BigFix prefetch compatibility uses both vendor SHA-1 and SHA-256 metadata. Retrieve the file through fetch_patch_files and pass its exact metadata. Do not calculate SHA3-256 and place it in a sha1 or sha256 field.

Generated XML is not written to disk

The server returns generated XML in the MCP tool response; it does not write a Fixlet file to a configured output directory. Save the reviewed response through the MCP client or an approved content workflow. If that save fails, check the client user's permissions and available disk space.

Service commands fail

Run installation and removal commands from an Administrator PowerShell session. Keep the same --workspace location used at installation when you reinstall or diagnose service configuration.