Skip to content

Troubleshooting Guide

Solutions to common issues when using the RDLC to DevExpress converter.

Quick Diagnostics

# Check MCP server configuration
cat ~/.cursor/mcp.json

# Verify conversion service is accessible (if running separately)
curl http://localhost:5000/health

# Check if DevExpress tool exists
ls data/vendor/ReportsImport.exe

Service Issues

Tool Not Found

Symptom: "Tool 'convert_rdlc_to_devexpress' not found"

Solutions:

  1. Restart Cursor completely (most common fix)

  2. Verify ~/.cursor/mcp.json configuration: 

    {
  "mcpServers": {
    "user-rdlc-converter": {
      "command": "node",
      "args": ["/absolute/path/to/project/src/McpServer/dist/index.js"]
    }
  }
}

Replace /absolute/path/to/project with your actual project path. Use forward slashes even on Windows.

  1. Check MCP server build: 

    cd src/McpServer
npm run build
# Should create dist/index.js

  2. Verify Node.js is installed: 

    node --version
# Should show v18 or higher

MCP Server Not Starting

Symptom: Tool calls fail or timeout

Solutions:

  1. Check MCP server build: 

    cd src/McpServer
npm install
npm run build

  2. Verify path in mcp.json:

    • Use absolute path to dist/index.js
    • Use forward slashes even on Windows
    • Example: C:/path/to/project/src/McpServer/dist/index.js

  3. Check MCP Server Connection:

    • Settings → Tools & MCP → Installed MCP Servers
    • Turn ON/OFF
    • Check if connection dot is green

Conversion Service Not Running

Symptom: "Connection refused" or "Service unavailable"

Solutions:

  1. Start the conversion service: 

    cd src/ConversionService
dotnet run
# Should start on http://localhost:5000

  2. Check if port is available: 

    # Windows
netstat -ano | findstr :5000

# Linux/Mac
lsof -i :5000

  3. Change port if needed: Edit src/ConversionService/appsettings.json: 

    {
  "Urls": "http://localhost:5001"
}

Then update MCP server environment: 

{
  "mcpServers": {
    "user-rdlc-converter": {
      "env": {
        "API_URL": "http://localhost:5001"
      }
    }
  }
}

Conversion Issues

Conversion Fails

Symptom: "Conversion failed" error

The converter provides detailed error messages with:

  • What stage failed (Parsing, Tool Execution, Patching, etc.)
  • Which part of the report caused the issue
  • Suggested actions to fix it

Check conversion service health (if running separately): 

curl http://localhost:5000/health
# Expected: {"status":"ok",...}

Common Error Types:

Error Type Cause Solution Service Layer
RDLC Parsing Error Invalid XML, corrupted file Open in Visual Studio, check XML syntax RdlcParserService (Application)
DevExpress Tool Error Unsupported features, tool crash Verify RDLC is valid, update tool version DevExpressToolConversionStrategy (Infrastructure)
Subreport Not Found Missing subreport file Place all reports in same directory SubreportResolverService (Application)
Tool Missing DevExpress tool not installed Check DevExpressToolPath in appsettings.json DevExpressToolConversionStrategy (Infrastructure)
Conversion Timeout Report too complex Increase ToolExecutionTimeoutSeconds ResilientProcessExecutor (Infrastructure)
File Too Large Exceeds size limit Check MaxFileSizeMB in appsettings.json ReportConversionService (Application)

Error Message Example: 

[FAIL] Conversion failed at stage 'RDLC Parsing' for file 'Report.rdlc': 
The RDLC file contains invalid XML at Line 42, Position 15.

Suggested action: Open Report.rdlc in Visual Studio to check for XML errors.

View detailed logs:

  • Check Cursor's Developer Tools console (Help → Toggle Developer Tools)
  • If running conversion service separately, check its console output

DevExpress Tool Not Found

Symptom: "DevExpress conversion tool not found at: ..."

Solution: Check appsettings.json:

{
  "ReportConversion": {
    "DevExpressToolPath": "data/vendor/ReportsImport.exe"
  }
}

Verify tool exists: 

ls data/vendor/ReportsImport.exe

Fix path if needed:

  • Windows: Use forward slashes or escaped backslashes
  • Linux/Mac: Use absolute path if relative doesn't work

Subreports Not Found

Symptom: "Could not find subreport: SubreportName"

Solutions:

  1. Place all reports in same directory: 

    reports/
├── MainReport.rdlc
├── Subreport1.rdlc
└── Subreport2.rdlc

  2. Check subreport paths in RDLC:

    • Open main RDLC in text editor
    • Search for <Subreport>
    • Verify ReportName matches actual filename

  3. Use relative paths in RDLC subreport references

Performance Issues

Symptom: Conversion taking > 2 minutes

Solutions:

  1. Check system resources:

    • Open Task Manager (Windows) or Activity Monitor (Mac)
    • Verify CPU and memory availability

  2. Check for many subreports:

    • 10+ subreports can be slow
    • Each subreport is converted separately

  3. Optimize DevExpress tool execution:

    • Check ToolExecutionTimeoutSeconds in appsettings.json
    • Increase if needed for complex reports

  4. Restart conversion service: 

    # Stop with Ctrl+C, then restart
cd src/ConversionService
dotnet run

Development Issues

Build Failures

C# Build Errors: 

cd src/ConversionService
dotnet restore
dotnet build

TypeScript Build Errors: 

cd src/McpServer
npm install
npm run build

Missing Dependencies

Install all dependencies: 

# C# projects
dotnet restore

# MCP server
cd src/McpServer
npm install

Edge Cases and Special Scenarios

Reports with Custom Code

Symptom: "Expression contains custom code function - requires manual review"

Issue: RDLC reports using Code.FunctionName() cannot be auto-converted

Solutions:

  1. Locate custom code: 

    Open RDLC in text editor → Search for "<Code>" tag

  2. Rewrite in DevExpress:

    • Open REPX in DevExpress Designer
    • Go to Scripts tab
    • Rewrite functions in C# or VB.NET
    • Update expression references

  3. Alternative approach:

    • Move logic to application layer
    • Pass calculated values as parameters
    • Use calculated fields in dataset

Example: 

' RDLC Custom Code
Public Function CalculateDiscount(amount As Decimal) As Decimal
    If amount > 1000 Then Return amount * 0.1
    Return amount * 0.05
End Function

' DevExpress Script (in Report Designer → Scripts)
private decimal CalculateDiscount(decimal amount) {
    if (amount > 1000) return amount * 0.1m;
    return amount * 0.05m;
}

Reports with ReportItems References

Symptom: "ReportItems reference - use calculated field instead"

Issue: RDLC expressions like =ReportItems!TextBox1.Value refer to other controls

Solutions:

  1. Use calculated fields: 

    Create calculated field in dataset
Reference field instead of control

  2. Restructure expression: 

    Move logic to data source query
Use SQL expressions where possible

  3. Use parameters: 

    Pass values as parameters
Reference parameters in expressions

Example: 

' RDLC (Not supported)
=ReportItems!TotalAmount.Value * 0.1

' DevExpress (Solution 1: Calculated field)
=[CalculatedTax]

' Or (Solution 2: Direct expression)
=[TotalAmount] * 0.1

Multi-Value Parameters

Symptom: Parameter appears empty or shows single value

Issue: Multi-value parameters need configuration in DevExpress

Solutions:

  1. Configure parameter:

    • Open REPX in DevExpress Designer
    • Click on parameter
    • Set "Multi-Value" = True
    • Set "Allow Null" if needed

  2. Update expressions: 

    ' RDLC
=Join(Parameters!Categories.Value, ", ")

' DevExpress
=Join(?Categories, ', ')

  3. Update filter expressions:

    • Use "In" operator for filtering
    • Example: [Category] In (?SelectedCategories)

Nested Tablixes with Dynamic Columns

Symptom: "Complex nested structure - manual adjustment required"

Issue: Tables with dynamic number of columns (matrix layouts)

Solutions:

  1. Simplify layout:

    • Consider if dynamic columns are necessary
    • Use fixed columns if possible

  2. Use DevExpress Pivot Table:

    • Better suited for dynamic layouts
    • Configure in Report Designer

  3. Restructure data:

    • Pivot data in SQL query
    • Use fixed column layout

Not feasible?

  • May need to recreate table manually
  • DevExpress has different approach to dynamic columns

Reports with Drill-Through Actions

Symptom: Interactive features not working

Issue: RDLC drill-through actions need manual configuration

Solutions:

  1. DevExpress drill-through:

    • Use "Detail Report" bands
    • Configure drill-down groups

  2. Parameter-based navigation:

    • Use DevExpress report parameters
    • Configure sub-reports with parameters

  3. Application-level:

    • Handle navigation in application code
    • Show related reports on demand

Embedded Images Not Displaying

Symptom: Images show as placeholders or broken

Issue: Embedded resources not transferred

Solutions:

  1. Re-embed images: 

    Open REPX in DevExpress Designer
Select image control
Properties → Image → Browse
Select image file
Choose "Embed in report"

  2. Use external paths:

    • Store images in accessible location
    • Use file path or URL
    • Configure ImageUrl property

  3. Database images:

    • Store images in database
    • Bind to BLOB field
    • Configure data binding

Conditional Formatting Not Applied

Symptom: Colors, fonts, or visibility rules not working

Issue: RDLC formatting expressions need conversion

Solutions:

  1. DevExpress formatting rules:

    • Open REPX in DevExpress Designer
    • Select control
    • Add "Formatting Rule"
    • Configure condition and style

  2. Expression-based formatting: 

    // In BeforePrint event
if (([Amount] > 1000)) {
    xrLabel1.BackColor = Color.Yellow;
}

  3. Check conversion guide:

    • Lists formatting issues
    • Provides specific instructions

Data Binding Issues After Conversion

Symptom: Report shows no data or error messages

Solutions:

  1. Verify data source connection: 

    DevExpress Designer → Report Explorer → Data Sources
Check if data source is configured

  2. Re-bind data source:

    • Right-click report → Designer
    • Data Sources tab
    • Add new data source
    • Rebind controls

  3. Check parameter data types:

    • Verify parameter types match
    • Date parameters especially sensitive

  4. Test with sample data:

    • Use DevExpress preview
    • Check for SQL errors
    • Verify query syntax

Page Breaks Not Working

Symptom: Report doesn't break pages as expected

Solutions:

  1. Configure page breaks: 

    Select group header/footer
Properties → "Page Break" = "Before/After"

  2. KeepTogether issues:

    • Check "Can Shrink" / "Can Grow" properties
    • May need to adjust "Keep Together" settings

  3. Verify page margins:

    • Check margin settings
    • Ensure content fits within printable area

Localization/Globalization Issues

Symptom: Dates, numbers, or currencies showing wrong format

Solutions:

  1. Check report culture: 

    Report properties → Localization → Culture
Set appropriate culture (e.g., "da-DK" for Danish)

  2. Format strings: 

    Update format strings to match culture
Example: {0:dd-MM-yyyy} for European dates

  3. Decimal separators:

    • Verify comma vs. dot
    • Set appropriate culture

See Also

Last Updated: December 18, 2025