# How to Troubleshoot Common Issues in AI-Infra-Guard: Complete Diagnostic Guide

> Troubleshoot AI-Infra-Guard issues by validating YAML rules checking WebSocket connectivity and ensuring Python dependencies are met for scanning modules. Get your AI infrastructure guard working.

- Repository: [Tencent/AI-Infra-Guard](https://github.com/tencent/AI-Infra-Guard)
- Tags: how-to-guide
- Published: 2026-08-23

---

**To troubleshoot AI-Infra-Guard effectively, verify your YAML rule files with the built-in validator, check WebSocket connectivity between agents and the server, and ensure Python dependencies are installed for scanning modules.**

AI-Infra-Guard is a hybrid-stack AI security scanning platform maintained by Tencent that combines a Go-based core with Python sub-modules for extensible detection. Understanding its dual-language architecture and key file locations allows you to isolate failures quickly across the CLI, WebSocket API, database layer, and plugin systems.

## Architecture Overview: Where Problems Originate

AI-Infra-Guard's codebase is organized into distinct layers. Knowing these boundaries helps you route issues to the correct subsystem immediately.

- **CLI & Server Layer** (`cmd/cli/*`, `cmd/agent/*`): Entry points for the web service, command-line interface, and agent processes. Crashes here usually indicate configuration errors or CGO mismatches.
- **WebSocket & Task Engine** (`common/websocket/*`): Handles real-time bidirectional communication, task scheduling, and agent registration. Disconnects and registration failures stem from this layer.
- **Database & Persistence** (`pkg/database/*`): SQLite/JSON storage for scan tasks and results. Schema mismatches appear here.
- **HTTP Infrastructure** (`pkg/httpx/*`): Unified HTTP client with customizable options. Timeout and proxy issues originate in [`pkg/httpx/options.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/httpx/options.go).
- **Scanning Engines** (`internal/mcp/*`, `agent-scan/`, `mcp-scan/`): Core vulnerability detection written in Go, augmented by Python plugins. Missing vulnerabilities usually indicate rule parsing failures.
- **Static Rule Data** (`data/*`): YAML/JSON fingerprint and vulnerability definitions. Corrupted files here cause silent scan failures.

## Common Failure Scenarios and Diagnostics

### Segmentation Faults and Binary Crashes

If you encounter `./ai-infra-guard: signal: segmentation fault`, the Go binary was likely built against mismatched CGO libraries or is loading invalid configuration files.

1. Rebuild with the race detector to catch data races:

```bash
go build -race -o ai-infra-guard ./cmd/cli/main.go

```

2. Validate that configuration files in `data/` are syntactically correct:

```bash
go build -o yamlcheck ./cmd/yamlcheck/main.go
./yamlcheck data/fingerprints data/vuln data/vuln_en

```

Critical files to inspect: [`cmd/cli/main.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/cmd/cli/main.go) for entry-point logic and [`pkg/database/yaml_model.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/database/yaml_model.go) for YAML parsing errors.

### WebSocket Disconnects and "Connection Lost" Errors

When the web UI displays connection errors, the WebSocket server is unreachable or behind a misconfigured proxy.

1. Confirm the server is listening on the expected address:

```bash
netstat -tlnp | grep ai-infra-guard

```

2. Check [`common/websocket/config.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/config.go) for the correct bind address configuration.
3. Inspect [`common/websocket/server.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/server.go) for server-side connection handling and [`common/websocket/task_manager.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/task_manager.go) for task routing issues.

### Agent Registration Failures

Agents that fail to register typically cannot reach the WebSocket endpoint or have mismatched environment variables.

1. Verify the `AIG_SERVER` environment variable points to the correct host (e.g., `127.0.0.1:8088`):

```bash
export AIG_SERVER=127.0.0.1:8088
./ai-infra-guard agent

```

2. Review the registration logic in [`common/websocket/agent.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/agent.go) to ensure the handshake protocol matches between client and server.

### Missing Vulnerabilities in Scan Output

When scans complete but return no findings, rule files may not be loading or are outdated.

1. Run the YAML validator across all rule directories:

```bash
./yamlcheck data/fingerprints data/vuln data/vuln_en

```

2. Verify that [`pkg/database/model.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/database/model.go) correctly parses the stored results and that [`internal/mcp/scanner.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/internal/mcp/scanner.go) is executing the rule evaluation logic.

### HTTP Request Timeouts

Default timeouts may be too short for slow targets, or proxy settings may be incorrect.

1. Inspect [`pkg/httpx/options.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/httpx/options.go) for the `DefaultTimeout` constant.
2. Adjust via CLI flag `--timeout` or environment variable `HTTP_TIMEOUT`.
3. For debugging, enable verbose logging in your Go code:

```go
import (
    "github.com/Tencent/AI-Infra-Guard/pkg/httpx"
    "github.com/Tencent/AI-Infra-Guard/pkg/httpx/options"
    "time"
)

func main() {
    opts := []options.Option{
        options.WithDebug(true),
        options.WithTimeout(30 * time.Second),
    }
    client := httpx.NewClient(opts...)
    resp, err := client.Get("https://example.com")
    // Handle response
}

```

Key files: [`pkg/httpx/httpx.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/httpx/httpx.go) and [`pkg/httpx/response.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/httpx/response.go).

### Python Sub-module Crashes

Python-based scanners in `mcp-scan/` and `agent-scan/` crash when dependencies are missing.

1. Install requirements for the specific module:

```bash
pip install -r agent-scan/requirements.txt
pip install -r mcp-scan/requirements.txt

```

2. Execute the entry script directly to see tracebacks:

```bash
python agent-scan/main.py --help

```

## Diagnostic Code Examples

### Running a Local Scan Server and Client

Build the binary and launch the web server, then execute a scan in a separate terminal:

```bash

# Terminal 1: Build and start server

go build -o ai-infra-guard ./cmd/cli/main.go
./ai-infra-guard webserver --server 127.0.0.1:8088

# Terminal 2: Run scan

./ai-infra-guard scan -t http://127.0.0.1:8088

```

Relevant source files: [`cmd/cli/cmd/webserver.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/cmd/cli/cmd/webserver.go) and [`cmd/cli/cmd/scan.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/cmd/cli/cmd/scan.go).

### Adding a Custom MCP Plugin for Testing

Create [`internal/mcp/plugins/my_plugin.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/internal/mcp/plugins/my_plugin.go):

```go
package plugins

import (
    "github.com/Tencent/AI-Infra-Guard/internal/mcp"
)

type MyPlugin struct{}

func (p *MyPlugin) Name() string { return "my-plugin" }

func (p *MyPlugin) Scan(target string) ([]mcp.Finding, error) {
    // Custom scanning logic here
    return nil, nil
}

```

Register it in [`internal/mcp/plugins.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/internal/mcp/plugins.go):

```go
func init() {
    Register(&MyPlugin{})
}

```

## Key Source Files for Troubleshooting

Keep these file paths accessible when debugging:

- **CLI Entry**: [`cmd/cli/main.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/cmd/cli/main.go) - Top-level flag parsing and sub-command dispatch.
- **Agent Process**: [`cmd/agent/main.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/cmd/agent/main.go) - Agent startup and configuration.
- **WebSocket Server**: [`common/websocket/server.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/server.go) - API implementation and SSE fallback.
- **Task Coordination**: [`common/websocket/task_manager.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/task_manager.go) - Job scheduling and cancellation.
- **Database Schema**: [`pkg/database/model.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/database/model.go) - Entity definitions for tasks and results.
- **HTTP Client**: [`pkg/httpx/httpx.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/httpx/httpx.go) - Request builder and response handling.
- **MCP Core**: [`internal/mcp/scanner.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/internal/mcp/scanner.go) - Rule evaluation orchestration.
- **Rule Validation**: [`cmd/yamlcheck/main.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/cmd/yamlcheck/main.go) - Build target for the YAML validator.
- **Python Scanner**: [`agent-scan/main.py`](https://github.com/Tencent/AI-Infra-Guard/blob/main/agent-scan/main.py) - Python-based scan execution.
- **Static Rules**: `data/fingerprints/` and `data/vuln/` - Rule definitions requiring validation.

## Summary

- **Validate configurations first**: Use `./yamlcheck` to verify all YAML files in `data/` before investigating code issues.
- **Check connectivity layers**: Isolate WebSocket issues by verifying `AIG_SERVER` environment variables and inspecting [`common/websocket/server.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/server.go).
- **Rebuild with debug flags**: Use `go build -race` to detect concurrency issues in the Go core.
- **Verify Python environments**: Ensure [`requirements.txt`](https://github.com/Tencent/AI-Infra-Guard/blob/main/requirements.txt) dependencies are installed for `agent-scan` and `mcp-scan` modules.
- **Adjust HTTP timeouts**: Modify `DefaultTimeout` in [`pkg/httpx/options.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/httpx/options.go) or use `--timeout` flags for slow targets.

## Frequently Asked Questions

### How do I fix the "connection lost" error in the AI-Infra-Guard web UI?

This error indicates the WebSocket server is unreachable. Confirm the server process is running and listening on the correct port using `netstat -tlnp`, then verify the bind address in [`common/websocket/config.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/config.go) matches your proxy or network configuration.

### Why does AI-Infra-Guard crash with a segmentation fault on startup?

Segmentation faults typically occur due to CGO library mismatches or corrupted YAML configuration files. Rebuild the binary with `go build -race ./cmd/cli/main.go` to catch data races, and run `./yamlcheck` against all files in `data/fingerprints` and `data/vuln` to ensure valid syntax.

### How can I debug why my scan returns no vulnerabilities?

First validate your rule files are loading correctly using the YAML checker. If rules are valid, check [`internal/mcp/scanner.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/internal/mcp/scanner.go) to ensure the MCP engine is executing plugins, and verify [`pkg/database/model.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/database/model.go) for proper result serialization. Also confirm the target is actually vulnerable by testing against known-vulnerable sample data.

### What should I check when the AI-Infra-Guard agent fails to register with the server?

Ensure the `AIG_SERVER` environment variable points to the correct WebSocket endpoint (e.g., `127.0.0.1:8088`). Then inspect [`common/websocket/agent.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/agent.go) for the registration handshake logic and confirm no firewall rules are blocking the WebSocket port.