Troubleshooting

This guide covers common issues you may encounter when using RAP Builder and how to resolve them.

General Debugging Steps

Before diving into specific issues, try these steps:

1. Review the log file in the RAPBuilderLogs/ directory (or your custom location).

2. Verify your project builds first - RAP Builder operates on compiled output, so compile your solution before running relsvr-rap build.

3. Check file paths - all paths in build.xml are relative to the --source directory.

4. Check exit codes - exit code 1 indicates a general error (bad path, missing file), while exit code 4 indicates a validation or build logic error (schema mismatch, SDK version failure).

5. Enable debug logging for deeper diagnostics. Debug level output is primarily intended for Relativity engineering to troubleshoot tool behavior, so use this as a last resort when the steps above don't surface the issue:

   Copy

   relsvr-rap build ... --log-level Debug --log-file logs/debug.log
   

Build Failures

RAP File Not Created

Symptoms:

• Build appears to complete but no .rap file exists in the output directory.
• No error messages displayed.

Solutions:

1. Check the <Destination> path in build.xml. The path is relative to --source:

   Copy

   <Destination>Artifacts\MyApp.rap</Destination>
   

2. Verify the output directory exists or can be created by RAP Builder.

3. Check file system permissions on the output directory.

4. Enable debug logging to see what happened:

Exit Code 1

Symptoms:

• Build fails and returns exit code 1.
• Error messages appear in console output.

Solutions:

1. Review the log file in the RAPBuilderLogs/ directory.

2. Look for specific error messages - they indicate exactly what failed. See Validation and Errors.

3. If the failure is caused by SDK version errors (for example, an SDK version mismatch reported during validation), fix the SDK version references in your project.

Server 2026 Build Fails on Framework Warnings

Symptoms:

• A build targeting --relativity-server-release 2026 fails with exit code 4.
• The log contains Warning-level findings that one or more assemblies do not target .NET Framework 4.8.1.

Cause: For Server 2026, RAP Builder verifies that every assembly in the RAP (including third-party dependencies) targets .NET Framework 4.8.1. Assemblies on an earlier framework produce Warning-level findings, and because --warnings-as-errors defaults to true, those warnings fail the build. Server 2024 and 2025 builds are not affected.

Solutions:

1. Retarget your own assemblies to .NET Framework 4.8.1 and rebuild.

2. Update or replace third-party dependencies that still target an earlier framework.

3. While migrating, pass --warnings-as-errors false to complete the build and review the findings without failing:

   Copy

   relsvr-rap build ... --relativity-server-release 2026 --warnings-as-errors false
   

See Target Framework Validation (Server 2026) for details.

Configuration Problems

Path Not Found

Error:

Could not find file 'C:\MyApp\Source\MyApp\bin\MyApp.dll'

Cause: An assembly, resource file, or custom page path in build.xml resolves to a location that doesn't exist.

Solutions:

1. Verify your --source parameter points to the correct root directory:

   Copy

   relsvr-rap build --source C:\MyApp --input DevelopmentScripts\build.xml ...
   

2. Understand path resolution. Paths in build.xml are joined with --source:

   • --source = C:\MyApp
   • build.xml entry = Source\MyApp\bin\MyApp.dll
   • Resolved path = C:\MyApp\Source\MyApp\bin\MyApp.dll

3. Build before running RAP Builder:

   Copy

   dotnet build --configuration Release
   relsvr-rap build -s . -i DevelopmentScripts\build.xml -v 1.0.0 -r 2024
   

Case Sensitivity

RAP Builder treats all file names and GUIDs as case-sensitive. The most common case-sensitivity issues are:

Custom Page Issues

Custom Page GUID Mismatch

Error:

Custom Page <guid> in schema was not found

Solution: Ensure the GUID in build.xml matches the <Guid> in application.xml exactly:

build.xml:

<CustomPage guid="f28fb91d-16ea-40f3-b869-a08b1cd7159c">...</CustomPage>

application.xml:

<CustomPage>
  <Guid>f28fb91d-16ea-40f3-b869-a08b1cd7159c</Guid>
  ...
</CustomPage>

Custom Page Directory Not Found

Error:

Custom page directory not found

Solution: The <CustomPage> element text in build.xml should point to the directory containing the custom page files - not to an individual file:

<CustomPage guid="...">Source\MyApp.CustomPage\MyPage</CustomPage>

SDK Validation Issues

Multiple SDK Versions Detected

Cause: Your project has transitive dependencies pulling in different versions of the same SDK assembly.

Solutions:

1. Use central package version management in a Directory.Build.props file:

   Copy

   <Project>
     <ItemGroup>
       <PackageReference Update="Relativity.ObjectManager" Version="5000.0.2.0" />
     </ItemGroup>
   </Project>
   

2. Pin the version in your .csproj:

   Copy

   <PackageReference Include="Relativity.ObjectManager" Version="5000.0.2.0" />
   

Invalid XML

Error:

Failed to parse build.xml: Invalid XML format

Solutions:

1. Validate your XML files with an XML validator or use --log-level Debug to see parsing details.

2. Check for common XML issues:

   • Missing closing tags (e.g., <Assembly> without </Assembly>)
   • Unescaped special characters - use XML entities: | Character | Entity | |-----------|--------| | < | < | | > | > | | & | & | | " | " | | ' | ' |
   • Incorrect nesting or structure

Log File Reference

Default Log Location

Logs are written to RAPBuilderLogs/log_<ddMMyyyy_HHmmss>.txt in the current working directory.

Custom Log Location

relsvr-rap build ... --log-file C:\logs\rapbuilder.log

Log Levels Reference

What to Look For in Logs

• [Error] entries - Direct cause of build failures.
• [Warning] entries - Non-critical or advisory issues that do not by themselves fail the build.
• [Debug] entries - File read operations, path resolutions, and hash computations (visible at Debug or Verbose level).

Tool Not Found

relsvr-rap is Not Recognized

Error:

relsvr-rap : The term 'relsvr-rap' is not recognized as the name of a cmdlet, function, script file, or operable program.

Cause: The Relativity.Server.RAPTool .NET tool is not installed or not on your PATH.

Solutions:

1. Install globally:

   Copy

   dotnet tool install --global Relativity.Server.RAPTool
   

   If the .nupkg was downloaded locally:

   Copy

   dotnet tool install --global Relativity.Server.RAPTool --add-source C:\path\to\local\folder
   

2. Verify installation:

   Copy

   dotnet tool list --global | Select-String "Relativity.Server.RAPTool"
   

3. Ensure the .NET tools directory is on your PATH. The global tools directory is typically %USERPROFILE%\.dotnet\tools.

Getting Help

If you cannot resolve an issue using this guide:

1. Run the build with --log-level Debug and review the full log output.
2. Verify your build.xml and application.xml against the Configuration Reference.