# How to Diagnose and Fix Model Connection Issues in AntSK: A Complete Debugging Guide

> Troubleshoot AntSK model connection issues. Learn common causes like endpoint misconfiguration and network blocks. Debug your AI model connections effectively with this guide.

- Repository: [AIDotNet/antsk](https://github.com/aidotnet/antsk)
- Tags: debugging-guide
- Published: 2026-02-24

---

**Model connection issues in AntSK typically stem from misconfigured endpoint URLs, incorrect AI type mappings, or network-level blocks that prevent the custom `OpenAIHttpClientHandler` from rewriting requests properly.**

AntSK is an open-source AI knowledge management platform that connects to large language models (LLMs) and embedding services through a centralized HTTP pipeline. When your application fails to reach a model, the root cause usually lies in one of five distinct layers—from database configuration errors to Semantic Kernel SDK runtime exceptions. Understanding how the `OpenAIHttpClientHandler` in the `aidotnet/antsk` repository processes these requests is essential for rapid troubleshooting.

## Understanding the Model Connection Pipeline in AntSK

AntSK routes all model traffic through a custom HTTP handler designed to support multiple AI providers. The pipeline involves three core components:

- **`OpenAIHttpClientHandler`** ([`src/AntSK.Domain/Utils/OpenAIHttpClientHandler.cs`](https://github.com/aidotnet/antsk/blob/main/src/AntSK.Domain/Utils/OpenAIHttpClientHandler.cs)): Intercepts HTTP requests and rewrites the URI to match the configured endpoint while preserving the Semantic Kernel path (e.g., `/v1/chat/completions`).
- **`KernelService`** ([`src/AntSK.Domain/Domain/Service/KernelService.cs`](https://github.com/aidotnet/antsk/blob/main/src/AntSK.Domain/Domain/Service/KernelService.cs)): Builds Semantic Kernel instances for chat completion, selecting the appropriate client based on the `AIType` enum.
- **`KMService`** ([`src/AntSK.Domain/Domain/Service/KMService.cs`](https://github.com/aidotnet/antsk/blob/main/src/AntSK.Domain/Domain/Service/KMService.cs)): Constructs Kernel Memory instances for embedding and retrieval operations.

When `KernelService.GetKernelByApp` retrieves a model record from the `AIModels` table, it passes the endpoint to `OpenAIHttpClientHandlerUtil.GetHttpClient`, which creates an `HttpClient` with a 10-minute timeout.

## Common Causes of Model Connection Failures

### Misconfigured Model Settings in AIModels

The `AIModels` entity ([`src/AntSK.Domain/Repositories/Setting/AIModel/AIModels.cs`](https://github.com/aidotnet/antsk/blob/main/src/AntSK.Domain/Repositories/Setting/AIModel/AIModels.cs)) stores the four critical connection parameters. Errors here account for the majority of connection failures:

- **Invalid `EndPoint` URL**: Missing scheme (`http://` or `https://`), incorrect host, or wrong port. The handler expects a URL matching the regex `^(https?)://([^/:]+)(:\d+)?/(.*)`.
- **Non-existent `ModelName`**: The model identifier does not exist on the target service (e.g., requesting `gpt-4` from a local Ollama instance).
- **Revoked or empty `ModelKey`**: The API key is missing, expired, or lacks permissions for the specified model.

### URL Rewriting Errors in OpenAIHttpClientHandler

The `SendAsync` method (lines 44-77 in [`OpenAIHttpClientHandler.cs`](https://github.com/aidotnet/antsk/blob/main/OpenAIHttpClientHandler.cs)) parses the configured endpoint and reconstructs the request URI. If the endpoint string fails the regex match, the handler cannot determine the correct host and port, causing requests to route to an invalid address.

Additionally, proxy handling logic may inadvertently strip the path segments (`/v1/chat/completions` or `/v1/embeddings`) required by the Semantic Kernel SDK.

### AI Type Mismatches Between Client and Service

AntSK supports multiple providers via the `AIType` enum (`OpenAI`, `AzureOpenAI`, `SparkDesk`, etc.). The `WithTextGenerationByAIType` method in [`KernelService.cs`](https://github.com/aidotnet/antsk/blob/main/KernelService.cs) (lines 84-151) and [`KMService.cs`](https://github.com/aidotnet/antsk/blob/main/KMService.cs) (lines 93-124) uses a switch statement to invoke the correct builder method.

Selecting `AIType.OpenAI` for an Azure OpenAI endpoint (or vice versa) results in authentication errors or 404 responses because the SDK generates incorrect request headers and URL patterns.

### Network and Timeout Issues

Environmental factors frequently block connectivity:

- **Firewall restrictions**: Outbound traffic to the model endpoint is blocked.
- **TLS/SSL validation failures**: Self-signed certificates on private LLM deployments trigger `HttpRequestException`.
- **Request timeouts**: The default 10-minute timeout (`OpenAIHttpClientHandlerUtil.GetHttpClient`, line 98) may be insufficient for large embedding batches or slow local models.

### Runtime Exceptions from the Semantic Kernel SDK

Unhandled exceptions from the underlying SDK—such as `HttpRequestException`, `TaskCanceledException` (timeout), or deserialization errors—bubble up through the kernel builder calls (e.g., `builder.AddOpenAIChatCompletion` in [`KernelService.cs`](https://github.com/aidotnet/antsk/blob/main/KernelService.cs), line 88). These typically surface in the API controller logs (e.g., [`OpenController.cs`](https://github.com/aidotnet/antsk/blob/main/OpenController.cs), lines 34-40).

## Step-by-Step Debugging Steps for AntSK Model Connections

Follow this systematic approach to isolate and resolve connection failures.

### 1. Enable Development Logging

Set the environment variable to capture full request and response payloads:

```bash
export ASPNETCORE_ENVIRONMENT=Development

```

The `OpenAIHttpClientHandler` logs the rewritten URI and payload at lines 26-33 and 82-86 using Serilog.

### 2. Verify the AIModels Database Record

Inspect the configuration stored in the `AIModels` table:

```csharp
var chatModel = _aIModels_Repositories.GetFirst(p => p.Id == app.ChatModelID);
Console.WriteLine($"Endpoint: {chatModel.EndPoint}");
Console.WriteLine($"Model: {chatModel.ModelName}");
Console.WriteLine($"Type: {chatModel.AIType}");

```

Ensure the `EndPoint` matches the regex pattern `^(https?)://([^/:]+)(:\d+)?/(.*)` and includes the trailing slash if required.

### 3. Test Connectivity with a Raw HTTP Client

Bypass the Semantic Kernel pipeline to verify network reachability:

```csharp
using AntSK.Domain.Utils;

var httpClient = OpenAIHttpClientHandlerUtil.GetHttpClient("http://localhost:11434/");
var payload = new
{
    model = "llama2",
    messages = new[] { new { role = "user", content = "Hello" } },
    stream = false
};
var json = System.Text.Json.JsonSerializer.Serialize(payload);
var response = await httpClient.PostAsync(
    "/v1/chat/completions",
    new StringContent(json, Encoding.UTF8, "application/json"));

Console.WriteLine(await response.Content.ReadAsStringAsync());

```

If this succeeds but the kernel fails, the issue lies in the `AIType` configuration or the kernel builder setup.

### 4. Inspect the Rewritten URL

Check the Serilog output for entries tagged with `【模型服务接口调用-<guid>,host:<EndPoint>】`. Verify that the host and path match your expectations. If the host is missing or the path is truncated, the regex in `OpenAIHttpClientHandler` failed to parse the endpoint.

### 5. Validate the AI Type Switch

Set a breakpoint in `KernelService.WithTextGenerationByAIType` (lines 84-151) or `KMService.WithTextGenerationByAIType` (lines 93-124). Step through the switch statement to confirm the correct `builder.Add*` method is invoked for your provider (e.g., `AddOpenAIChatCompletion` for OpenAI, `AddAzureOpenAIChatCompletion` for Azure).

### 6. Adjust Timeout Settings

For slow local models or large embedding batches, increase the timeout in `OpenAIHttpClientHandlerUtil.GetHttpClient`:

```csharp
// Line 98 in OpenAIHttpClientHandlerUtil.cs
httpClient.Timeout = TimeSpan.FromMinutes(20); // Increase from default 10 minutes

```

### 7. Review Controller Logs

Examine the exception details in the API controller (e.g., [`OpenController.cs`](https://github.com/aidotnet/antsk/blob/main/OpenController.cs) lines 34-40). The Serilog output will contain the full stack trace from the Semantic Kernel SDK, revealing whether the failure is authentication (401), not found (404), or a network timeout.

### 8. Perform Network Diagnostics

From the host running AntSK, verify basic connectivity:

```bash
curl -v http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"llama2","messages":[{"role":"user","content":"hi"}]}'

```

If `curl` fails, the issue is environmental (firewall, DNS, or the model service is not running).

### 9. Isolate with Mock Services

Temporarily switch the `AIType` to `Mock` in the database to verify the rest of the pipeline:

```csharp
// KernelService.cs lines 133-136
AIType.Mock => builder
    .AddMockTextCompletion()
    .AddMockChatCompletion()

```

If the application works with the mock, the failure is definitely in the external model configuration or network path.

## Code Examples for Testing Model Connectivity

### Testing the HTTP Handler Directly

Use this snippet to verify that `OpenAIHttpClientHandler` correctly rewrites URLs for your specific endpoint:

```csharp
using System.Text;
using System.Text.Json;
using AntSK.Domain.Utils;

// Configure your actual endpoint from AIModels
string endpoint = "https://api.openai.com/v1/";
var httpClient = OpenAIHttpClientHandlerUtil.GetHttpClient(endpoint);

// Prepare a minimal chat completion request
var requestBody = new
{
    model = "gpt-3.5-turbo",
    messages = new[] 
    { 
        new { role = "system", content = "You are a helpful assistant." },
        new { role = "user", content = "Hello" }
    },
    temperature = 0.7
};

var json = JsonSerializer.Serialize(requestBody);
var content = new StringContent(json, Encoding.UTF8, "application/json");

try
{
    var response = await httpClient.PostAsync("/v1/chat/completions", content);
    var responseString = await response.Content.ReadAsStringAsync();
    
    Console.WriteLine($"Status: {response.StatusCode}");
    Console.WriteLine($"Response: {responseString}");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Request failed: {ex.Message}");
}

```

This bypasses the Semantic Kernel entirely, isolating whether the issue is network-related or configuration-related.

### Using Mock Models for Isolation

When you need to verify that your application logic works independently of external services, configure a mock model:

```csharp
// First, create a mock model record in your database
var mockModel = new AIModels
{
    Id = "mock-debug-model",
    EndPoint = "http://localhost", // Not actually used
    ModelName = "mock-model",
    ModelKey = "fake-key",
    AIType = AIType.Mock  // Critical: set type to Mock
};

// Save to repository
_aIModels_Repositories.Insert(mockModel);

// Now use it with the kernel service
var app = new Apps { ChatModelID = mockModel.Id };
var kernel = kernelService.GetKernelByApp(app);

// Invoke a function - this will use the mock completion service
var result = await kernel.InvokeAsync(
    kernel.Plugins.GetFunction("ConversationSummaryPlugin", "SummarizeConversation"),
    new() { ["input"] = "Test input" });

Console.WriteLine(result.GetValue<string>());

```

The mock implementation is located in [`KernelService.cs`](https://github.com/aidotnet/antsk/blob/main/KernelService.cs) at lines 133-136, where `AddMockTextCompletion()` and `AddMockChatCompletion()` are registered when `AIType.Mock` is detected.

## Summary

- **Model connection issues in AntSK** originate from five distinct layers: database configuration (`AIModels`), HTTP handler rewriting (`OpenAIHttpClientHandler`), AI type selection (`KernelService`/`KMService`), network environment, and Semantic Kernel runtime exceptions.
- **Verify the endpoint format** in the database matches the regex `^(https?)://([^/:]+)(:\d+)?/(.*)` and includes the correct scheme, host, and port.
- **Use `OpenAIHttpClientHandlerUtil.GetHttpClient`** to test connectivity outside the Semantic Kernel pipeline, isolating network issues from configuration errors.
- **Check the AIType enum** in `KernelService.WithTextGenerationByAIType` to ensure the correct builder method (OpenAI, AzureOpenAI, etc.) is invoked for your endpoint.
- **Enable Development logging** to capture the full rewritten URI and request/response payloads in Serilog, revealing exactly where the pipeline fails.

## Frequently Asked Questions

### Why does AntSK return a 404 error when connecting to my local Ollama instance?

A 404 error typically indicates that the `EndPoint` URL in the `AIModels` table is missing the trailing path segment or the `ModelName` does not exist on the Ollama server. Verify that the endpoint follows the format `http://localhost:11434/` and that you have pulled the model (e.g., `llama2`) locally. Test with `curl http://localhost:11434/v1/chat/completions` to confirm the path is valid.

### How can I increase the timeout for slow local LLM responses?

The default timeout is set to 10 minutes in `OpenAIHttpClientHandlerUtil.GetHttpClient` at line 98. To increase this for slow local models or large embedding batches, modify the `HttpClient` timeout before it is returned:

```csharp
httpClient.Timeout = TimeSpan.FromMinutes(20);

```

Alternatively, when testing directly with `OpenAIHttpClientHandlerUtil.GetHttpClient`, set the timeout property on the returned instance before making the request.

### What is the fastest way to verify if my API key is valid without modifying the database?

Use the raw HTTP client test approach with `OpenAIHttpClientHandlerUtil.GetHttpClient` to bypass the Semantic Kernel entirely. Pass your endpoint and construct a minimal chat completion request with your API key in the authorization header. If this returns a 401, your key is invalid or revoked. If it succeeds but the kernel fails, the issue is likely an `AIType` mismatch in the database configuration.

### Why does my connection work with curl but fail in AntSK?

When `curl` succeeds but AntSK fails, the discrepancy usually lies in the `OpenAIHttpClientHandler` URL rewriting logic or the `AIType` selection. The handler parses the endpoint using a strict regex and reconstructs the URI; if your endpoint string lacks a trailing slash or includes unexpected query parameters, the rewritten URL may be malformed. Additionally, ensure the `AIType` enum value matches your service provider (OpenAI vs. AzureOpenAI), as the wrong builder method will generate incompatible request headers.