# How to Troubleshoot Common Issues with AI-Infra-Guard: A Complete Guide

> Troubleshoot common AI-Infra-Guard issues by addressing misconfigurations, missing resources, and runtime errors in its Go CLI, Python plugins, and WebSocket server. Resolve operational problems effectively.

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

---

**Most operational problems in AI-Infra-Guard stem from misconfiguration, missing runtime resources, or unexpected runtime errors across its Go-based CLI, Python plugins, and WebSocket server components.**

AI-Infra-Guard (AIG) is a multi-component security-scanning platform developed by Tencent that combines Go services, Python plugins, and a WebSocket-based UI. When you troubleshoot common issues with AI-Infra-Guard, understanding the specific failure points in its architecture—from option parsing in [`cmd/cli/main.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/cmd/cli/main.go) to database initialization in [`pkg/database/config.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/database/config.go)—allows you to isolate and resolve errors rapidly.

## Understanding the Component Architecture

AI-Infra-Guard consists of distinct layers where failures typically occur. The following table maps each component to its typical failure mode and source location:

| Component | Function | Common Failure | Source Location |
|-----------|----------|----------------|-----------------|
| **CLI Entry Point** | Parses flags and launches sub-commands | Flags ignored or immediate exit with `Program exiting` | [`cmd/cli/main.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/cmd/cli/main.go) |
| **Options Parser** | Validates proxy URLs, timeouts, targets | `invalid http proxy format` errors | [`internal/options/options.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/internal/options/options.go) |
| **WebSocket Server** | Serves UI and streams results | Binding to non-loopback addresses or firewall blocks | [`cmd/cli/cmd/webserver.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/cmd/cli/cmd/webserver.go) |
| **Database Layer** | Persists tasks and metadata | `创建数据库目录失败` (failed to create directory) | [`pkg/database/config.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/database/config.go) |
| **HTTPX Utilities** | Handles outbound HTTP scanning | Timeouts and malformed responses | [`pkg/httpx/httpx.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/httpx/httpx.go) |
| **Vulnerability Engine** | Loads YAML rule files | `read directory error` for fingerprints | [`pkg/vulstruct/advisory.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/vulstruct/advisory.go) |
| **MCP/Agent Scan** | Executes plugin-based scans | Plugin registration failures | [`internal/mcp/scanner.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/internal/mcp/scanner.go) |

## Resolving Startup and CLI Validation Errors

When the binary exits immediately with `gologger.Fatalf("Program exiting: …")`, the `Options.validateOptions()` function in [`internal/options/options.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/internal/options/options.go) has detected an illegal configuration value.

### Invalid Proxy URL Errors

The most common CLI failure occurs when the `-proxy-url` flag contains a malformed URL. The `validateProxyURL` function expects the format `scheme://[user:pass@]host:port`.

**Error symptom:**

```

invalid http proxy format …

```

**Solution:** Verify your proxy URL syntax:

```bash
ai-infra-guard scan -target http://127.0.0.1:8000 -proxy-url http://user:pwd@proxy.example.com:3128

```

If you do not require a proxy, omit the flag entirely or set it to an empty string to bypass validation.

## Fixing WebSocket Server Binding and Connectivity Issues

The WebSocket server in [`cmd/cli/cmd/webserver.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/cmd/cli/cmd/webserver.go) validates that listening addresses contain `127.0.0.1` for security. If you specify `0.0.0.0:8088` or a public interface, the server prints a warning (lines 43-45) but still attempts to start.

**Symptoms:** UI cannot connect to `http://localhost:8088` or "unsafe listening address" warnings appear.

**Fix:** Use the loop-back address explicitly:

```bash
ai-infra-guard webserver --server 127.0.0.1:8088

```

If you must bind to external interfaces, ensure your host firewall permits inbound traffic on the chosen port.

## Troubleshooting Database Initialization and Permission Errors

Database failures originate in [`pkg/database/config.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/database/config.go) where `InitDB` attempts to create the parent directory of the SQLite file (lines 58-61).

**Symptoms:** `创建数据库目录失败` or `无法打开数据库连接` errors.

**Root cause:** The process lacks permission to create the directory specified in `DB_PATH`, or the path is malformed.

**Solution:** Pre-create the directory with proper permissions:

```bash
export DB_PATH=$HOME/aig/db/tasks.db
mkdir -p $(dirname $DB_PATH)
chmod 755 $(dirname $DB_PATH)

```

If `DB_PATH` is unset, the default `db/tasks.db` resolves to the repository root, which may lack write permissions depending on your installation method.

## Diagnosing Target Scanning Timeouts and HTTP Errors

Scanning failures typically manifest in [`pkg/httpx/httpx.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/httpx/httpx.go) where `HTTPX.do()` (lines 109-122) applies the configured timeout. Unreachable targets or slow AI services trigger `error reading response` messages.

**Resolution steps:**

1. Increase the timeout threshold:

   ```bash
   ai-infra-guard scan -target http://127.0.0.1:8000 -timeout 30
   ```

2. Verify the target is a **running AI service endpoint**, not a repository URL.
3. Test connectivity independently with `curl` to isolate network issues from application errors.

## Resolving Fingerprint and Vulnerability Rule Loading Failures

The vulnerability engine in [`pkg/vulstruct/advisory.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/vulstruct/advisory.go) walks the `data/fingerprints` and `data/vuln` directories (line 61). Missing directories or malformed YAML trigger `read directory error` or "no rules found" messages.

**Fix:** Ensure the `data/` folder exists in your working directory. Validate rule syntax using the bundled checker:

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

```

Place custom rules in the appropriate subdirectories and re-run the checker before executing scans.

## Fixing MCP and Agent Plugin Registration Errors

Plugin failures occur in [`internal/mcp/scanner.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/internal/mcp/scanner.go) where `Scanner.RegisterPlugin` (line 138) validates plugin names against files in `data/mcp/`.

**Symptoms:** `RegisterPlugin` returns an error and the scan aborts without processing plugins.

**Solution:** List available plugins to verify the name exists:

```bash
ai-infra-guard mcp list

```

Ensure the `-plugin` argument matches a filename in `data/mcp/` exactly.

## Handling Unexpected Process Termination and Panics

Fatal exits wrapped by `gologger.WithError(err).Fatalln` indicate unrecoverable conditions such as corrupted databases, critical I/O failures, or missing configuration. These appear as `panic` or `Fatalf` messages with stack traces.

**Fix:** Examine the log line immediately preceding the stack trace to identify the resource failure—whether file permissions, environment variables, or network connectivity—and remediate the underlying condition.

## General Debugging Workflow

For issues not resolved by component-specific fixes, follow this systematic approach:

1. **Enable verbose logging** by setting `GOTRACEBACK=all` to capture full stack traces.
2. **Run with `-v`** (supported by most sub-commands) to view parsed options.
3. **Check container logs** if deploying via Docker using `docker logs <container>`, as these contain the same `gologger` output as host processes.
4. **Verify YAML integrity** with the `yamlcheck` utility before deployment.
5. **Use the API documentation** at `http://localhost:8088/docs/index.html` to manually invoke endpoints and inspect raw JSON error responses.

## Summary

- **CLI validation errors** in [`internal/options/options.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/internal/options/options.go) typically indicate malformed proxy URLs or missing required flags.
- **WebSocket binding issues** require loop-back addresses (`127.0.0.1`) unless you explicitly configure firewall rules for external access.
- **Database failures** in [`pkg/database/config.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/database/config.go) result from missing parent directories or insufficient permissions for the `DB_PATH` location.
- **Scanning timeouts** in [`pkg/httpx/httpx.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/httpx/httpx.go) resolve by increasing the `-timeout` value or verifying target service availability.
- **Rule loading errors** in [`pkg/vulstruct/advisory.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/vulstruct/advisory.go) require intact `data/` directories and valid YAML syntax verified by `yamlcheck`.
- **Plugin registration** in [`internal/mcp/scanner.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/internal/mcp/scanner.go) fails when plugin names do not match files in `data/mcp/`.

## Frequently Asked Questions

### Why does AI-Infra-Guard exit immediately with "Program exiting"?

The `Options.validateOptions()` function in [`internal/options/options.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/internal/options/options.go) detected an invalid configuration, most commonly a malformed proxy URL. Verify that `-proxy-url` follows the format `http://user:pass@host:port` or omit the flag entirely if no proxy is required.

### How do I fix "cannot open database" errors when starting the scanner?

This error originates in [`pkg/database/config.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/database/config.go) where `InitDB` cannot create the directory specified by `DB_PATH`. Pre-create the directory with `mkdir -p $(dirname $DB_PATH)` and ensure the process has write permissions, or unset `DB_PATH` to use the default location.

### Why does my scan return "Timeout / error handling" for valid targets?

The `HTTPX.do()` method in [`pkg/httpx/httpx.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/httpx/httpx.go) enforces the timeout specified by `-timeout`. Increase the timeout value for slow-responding AI services, and verify the target URL points to a running inference endpoint rather than a static repository page.

### Where should I place custom fingerprint or vulnerability rules?

Place custom YAML files in `data/fingerprints/` or `data/vuln/` respectively, then validate them with `./yamlcheck data/fingerprints data/vuln` before running scans. The loader in [`pkg/vulstruct/advisory.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/pkg/vulstruct/advisory.go) requires these directories to exist in your working directory.