Home / Documentation
Troubleshooting Guide
Common issues and solutions for AvaloniaUI.MCP server.
🚨 Server Issues
Server Won’t Start
Symptom
1
Error: The server failed to start or connection refused
Solutions
Check .NET Version
1
2
dotnet --version
# Should show 9.0.x or later
Verify Project Build
1
2
3
cd AvaloniaUI.MCP
dotnet clean
dotnet build
Check for Port Conflicts
1
2
3
4
5
6
# Kill any existing processes
pkill -f "AvaloniaUI.MCP"
# Start with verbose logging
export AVALONIA_MCP_LOG_LEVEL = Debug
dotnet run --project src/AvaloniaUI.MCP/AvaloniaUI.MCP.csproj
Validate Configuration
1
2
# Test server manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | dotnet run --project src/AvaloniaUI.MCP/AvaloniaUI.MCP.csproj
Server Crashes
Symptom
1
Unhandled exception: System.OutOfMemoryException
Solutions
Memory Management
1
2
3
4
5
6
# Enable server GC
export DOTNET_gcServer = 1
export DOTNET_gcConcurrent = 1
# Set memory limits
export DOTNET_GCHeapHardLimit = 400000000 # 400MB limit
Check Resource Usage
1
2
Use the DiagnosticTool: "Perform a health check"
Use the DiagnosticTool: "Force garbage collection"
Review Logs
1
2
export AVALONIA_MCP_LOG_LEVEL = Information
dotnet run --project src/AvaloniaUI.MCP/AvaloniaUI.MCP.csproj 2>&1 | tee server.log
Connection Issues
Symptom
1
MCP client cannot connect to server
Solutions
Verify STDIO Configuration
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"mcpServers" : {
"avalonia" : {
"command" : "dotnet" ,
"args" : [
"run" ,
"--project" ,
"/absolute/path/to/AvaloniaUI.MCP/src/AvaloniaUI.MCP/AvaloniaUI.MCP.csproj"
],
"cwd" : "/absolute/path/to/AvaloniaUI.MCP"
}
}
}
Test Connection
1
2
# Manual test
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | dotnet run --project src/AvaloniaUI.MCP/AvaloniaUI.MCP.csproj
Check Permissions
1
2
3
4
5
# Ensure executable permissions
chmod +x src/AvaloniaUI.MCP/bin/Debug/net9.0/AvaloniaUI.MCP
# Check file access
ls -la src/AvaloniaUI.MCP/AvaloniaUI.MCP.csproj
Symptom
1
Error: Tool execution failed with status code 1
Solutions
Check Tool Metrics
1
Use DiagnosticTool: "Get server metrics"
Validate Input Parameters
1
2
"Validate my project name 'My-Invalid@Name'"
# Should suggest valid alternatives
Test Individual Tools
1
2
"Test the echo tool with message 'hello world'"
# Should respond with the echoed message
Validation Errors
Symptom
1
Error: Invalid XAML syntax
Solutions
Get Detailed Validation
1
"Validate this XAML and provide detailed error information"
Check Common Issues
Missing namespace declarations
Unclosed tags
Invalid property names
Binding syntax errors
Use Incremental Validation
1
2
"Validate just the Window tag first"
"Now validate with the StackPanel added"
Generation Failures
Symptom
1
Error: Project generation failed
Solutions
Check Directory Permissions
1
2
# Ensure write access
touch test-file.txt && rm test-file.txt
Validate Project Name
1
"Is 'MyApp123' a valid project name?"
Try Simplified Generation
1
2
"Create a basic project instead of MVVM"
"Generate only the essential files"
Slow Response Times
Symptom
1
Tool responses taking > 5 seconds
Solutions
Check Cache Performance
1
2
Use DiagnosticTool: "Get server metrics"
# Look for cache hit rate < 80%
Clear Cache
1
Use DiagnosticTool: "Clear resource cache"
Optimize Environment
1
2
3
4
# Production settings
export ENVIRONMENT = production
export AVALONIA_MCP_LOG_LEVEL = Warning
export DOTNET_gcServer = 1
Monitor Resource Usage
1
Use DiagnosticTool: "Force garbage collection and show memory stats"
High Memory Usage
Symptom
1
Server memory usage > 500MB
Solutions
Check Memory Pressure
1
2
Use DiagnosticTool: "Perform health check"
# Will show memory usage warnings
Restart Server Periodically
1
2
# Schedule periodic restarts for long-running instances
# Add to cron: 0 */6 * * * pkill -f AvaloniaUI.MCP
Optimize Caching
1
2
# Reduce cache size
export AVALONIA_MCP_CACHE_SIZE = 50 # Default 100
🐛 Development Issues
Build Errors
Symptom
1
CS0246: The type or namespace name could not be found
Solutions
Restore Packages
1
2
3
dotnet clean
dotnet restore
dotnet build
Check Package Versions
1
2
dotnet list package --outdated
dotnet list package --vulnerable
Verify SDK Version
1
2
dotnet --list-sdks
# Should include 9.0.x
Test Failures
Symptom
1
Test run failed: X tests failed
Solutions
Run Specific Test Categories
1
2
3
4
5
# Run only unit tests
dotnet test --filter Category = Unit
# Run only integration tests
dotnet test --filter Category = Integration
Check Test Output
1
dotnet test --verbosity detailed
Reset Test Environment
1
2
3
# Clean test artifacts
rm -rf tests/* /bin tests/* /obj
dotnet test
Runtime Exceptions
Symptom
1
System.ArgumentNullException: Value cannot be null
Solutions
Enable Detailed Logging
1
export AVALONIA_MCP_LOG_LEVEL = Trace
Check Input Validation
1
"Test input validation with empty parameters"
Use Error Handling Tools
1
2
"Show me the last 10 error events"
Use DiagnosticTool: "Test logging at error level"
📋 Diagnostic Commands
Health Monitoring
1
2
3
4
"Perform a comprehensive health check"
"Get current server metrics"
"Show memory usage and GC statistics"
"Test all service components"
1
2
3
4
"Force garbage collection"
"Clear all caches"
"Show cache hit rates"
"Display tool execution statistics"
Logging and Debug
1
2
3
4
"Test logging functionality at debug level"
"Show recent error events"
"Display server configuration"
"Check file system permissions"
🔧 Environment Variables
Logging Configuration
1
2
export AVALONIA_MCP_LOG_LEVEL = Debug # Trace|Debug|Information|Warning|Error|Critical
export ENVIRONMENT = development # development|staging|production
1
2
3
export DOTNET_gcServer = 1 # Enable server GC
export DOTNET_gcConcurrent = 1 # Enable concurrent GC
export DOTNET_GCHeapHardLimit = 400000000 # 400MB memory limit
Cache Configuration
1
2
export AVALONIA_MCP_CACHE_SIZE = 100 # Number of cached items
export AVALONIA_MCP_CACHE_TTL = 3600 # Cache TTL in seconds
📞 Getting Help
Self-Diagnosis
Use DiagnosticTool for health checks
Review server logs with debug level
Test individual components
Check environment configuration
Reporting Bugs
When reporting issues, include:
Server version and .NET version
Operating system and architecture
Complete error message and stack trace
Steps to reproduce
Server configuration and environment variables
Output from health check diagnostic
Example Bug Report Template
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
## Bug Report
**Environment:**
- OS: Ubuntu 22.04 / Windows 11 / macOS 13
- .NET Version: 9.0.x
- Server Version: 1.0.0
**Issue:**
Brief description of the problem
**Steps to Reproduce:**
1. Start server with: `dotnet run...`
2. Execute command: "Create project..."
3. Error occurs
**Expected Behavior:**
What should happen
**Actual Behavior:**
What actually happens
**Logs:**
[Paste relevant log output]
1
2
**Health Check Output:**
[Output from diagnostic health check]
1
2
3
**Additional Context:**
Any other relevant information