Troubleshooting

Common issues and solutions when building or developing with Dalamud

This guide helps you resolve common issues encountered when building, testing, or developing with Dalamud.

Build Issues

.NET SDK Problems

SDK version not found

Error:

The current .NET SDK does not support targeting .NET 10.0

Cause: Missing or incorrect .NET SDK version.

Solutions:

1. Let build script download SDK

   The build scripts automatically download the correct SDK:

   # Windows
   .\build.ps1
   
   # Linux
   ./build.sh
   

   SDK is downloaded to .nuke/temp/dotnet-win or .nuke/temp/dotnet-unix

2. Manual SDK installation

   Download .NET 10.0 SDK from https://dot.net

   Verify installation:

   dotnet --version
   # Should show: 10.0.x
   
3. Check global.json

   Ensure global.json is not corrupted:

   {
     "sdk": {
       "version": "10.0.0",
       "rollForward": "latestMinor",
       "allowPrerelease": true
     }
   }
   

SDK rollforward errors

Error:

A compatible SDK version for global.json could not be found

Solution: The SDK will roll forward to newer minor versions. Ensure you have at least version 10.0.0 or let the build script handle it.

Check installed SDKs:

dotnet --list-sdks

Preview SDK required

Error:

Preview SDK required but not enabled

Solution: The global.json enables preview features:

"allowPrerelease": true

This is required because Dalamud uses LangVersion: preview for C# language features.

MSBuild and C++ Compilation

MSBuild not found

Error:

MSBuild.exe is not recognized as an internal or external command

Solutions:

1. Install Visual Studio 2022

   • Download from visualstudio.microsoft.com
   • Install with “Desktop development with C++” workload

2. Use Developer Command Prompt

   • Open “Developer Command Prompt for VS 2022”
   • Navigate to Dalamud directory
   • Run ./build.ps1

3. Add MSBuild to PATH

   # Typical location:
   C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin
   

Platform Toolset v143 missing

Error:

The build tools for v143 (Platform Toolset = 'v143') cannot be found

Cause: Missing C++ build tools for Visual Studio 2022.

Solution: Run Visual Studio Installer:

1. Modify your VS 2022 installation
2. Select “Desktop development with C++”
3. Ensure these components are checked:
   • MSVC v143 - VS 2022 C++ x64/x86 build tools
   • Windows 10 SDK (latest version)
   • C++ CMake tools for Windows

Windows SDK not found

Error:

Windows SDK version 10.0 was not found

Solution: Install Windows 10 SDK:

• Via Visual Studio Installer (Individual Components tab)
• Or download standalone from Microsoft

The project uses:

<WindowsTargetPlatformVersion>10.0</WindowsTargetPlatformVersion>

MASM not found

Error:

MASM (x64) not found

Cause: Dalamud.Boot uses MASM for assembly files (rewrite_entrypoint_thunks.asm).

Solution: Install via Visual Studio Installer:

• Individual Components → Compilers → MASM (x64)

Submodule Issues

Submodule not initialized

Error:

The type or namespace 'FFXIVClientStructs' could not be found

Cause: Git submodules not initialized.

Solution:

git submodule update --init --recursive

Verify submodules:

git submodule status
# Should show commits, not dashes:
# 1234567... lib/FFXIVClientStructs (v1.0.0)

Submodule detached HEAD

Warning:

You are in 'detached HEAD' state in submodule

Explanation: This is normal for submodules. They’re pinned to specific commits.

To update submodule:

cd lib/FFXIVClientStructs
git checkout master
git pull origin master
cd ../..
git add lib/FFXIVClientStructs
git commit -m "chore: update FFXIVClientStructs"

Submodule permission denied (SSH)

Error:

Permission denied (publickey) when cloning submodules

Solution: Convert submodule URLs from SSH to HTTPS:

git config --global url."https://github.com/".insteadOf [e-mail]:
git submodule sync
git submodule update --init --recursive

Dependency Problems

NuGet restore failures

Error:

Unable to load the service index for source https://api.nuget.org/v3/index.json

Solutions:

1. Check network connectivity

   curl https://api.nuget.org/v3/index.json
   

2. Clear NuGet cache

   dotnet nuget locals all --clear
   ./build.ps1 Restore
   

3. Check firewall/proxy settings Configure NuGet proxy if behind corporate firewall

Package version conflicts

Error:

NU1608: Detected package version outside of dependency constraint

Cause: Dalamud uses Central Package Management (Directory.Packages.props).

Solution: Package versions are centrally managed. Don’t specify versions in individual projects:

<!-- Correct -->
<PackageReference Include="Newtonsoft.Json" />

<!-- Incorrect -->
<PackageReference Include="Newtonsoft.Json" Version="13.0.1" />

Version is defined in Directory.Packages.props:

<PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />

Missing native dependencies

Error:

Could not load file or assembly 'cimgui.dll'

Cause: Native C++ DLLs not built.

Solution: Ensure full build completes:

./build.ps1 Clean
./build.ps1 Compile

Check that these exist in bin/Debug or bin/Release:

• cimgui.dll
• cimplot.dll
• cimguizmo.dll
• Dalamud.Boot.dll

Runtime Issues

Dalamud fails to inject

Symptoms: Game launches but Dalamud doesn’t load.

Debug steps:

1. Check XIVLauncher logs

   • %APPDATA%\XIVLauncher\output.log
   • Look for injection errors

2. Verify Dalamud files

   • %APPDATA%\XIVLauncher\addon\Hooks\dev\
   • Ensure all DLLs are present

3. Check for antivirus interference

   • Add exception for XIVLauncher directory
   • Add exception for FFXIV directory

4. Test with clean profile

   • Rename %APPDATA%\XIVLauncher temporarily
   • Launch with fresh configuration

Plugin compatibility errors

Error:

Could not load plugin: API version mismatch

Cause: Breaking API changes in your build.

Solution: Check API compatibility:

# Compare against staging
apicompat -l "old\Dalamud.dll" -r "new\Dalamud.dll"

If intentional breaking change:

• Update DalamudVersion in Dalamud.csproj
• Document migration path
• Update changelog

Game crashes on startup

Possible causes:

• Invalid hooks
• Memory corruption
• Incompatible game version

Debug approach:

1. Enable crash dumps

   • DalamudCrashHandler should generate dumps
   • Check %APPDATA%\XIVLauncher\crashes\

2. Test without plugins

   • Disable all third-party plugins
   • Narrow down to specific component

3. Check game version

   • Ensure FFXIVClientStructs is up to date
   • Game updates may break hooks

Test Failures

Tests not discovered

Symptoms: Test Explorer shows no tests.

Solutions:

1. Rebuild test project

   dotnet build Dalamud.Test/Dalamud.Test.csproj
   

2. Verify xunit packages

   <PackageReference Include="xunit.v3" />
   <PackageReference Include="xunit.v3.assert" />
   <PackageReference Include="xunit.runner.visualstudio" />
   

3. Check test class is public

   public class MyTests  // Must be public
   {
       [Fact]
       public void Test() { }  // Must be public
   }
   

File not found in tests

Error:

FileNotFoundException: Could not find file 'test_data.txt'

Cause: Test data files not copied to output.

Solution: Add to .csproj:

<ItemGroup>
  <None Update="test_data.txt">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

Or use Assembly.GetExecutingAssembly().Location to locate files.

Tests pass locally, fail in CI

Common causes:

1. Culture differences

   // Bad - culture dependent
   Assert.Equal("1.5", value.ToString());
   
   // Good - culture invariant
   Assert.Equal("1.5", value.ToString(CultureInfo.InvariantCulture));
   

2. Path separators

   // Bad
   var path = "folder\\file.txt";
   
   // Good
   var path = Path.Combine("folder", "file.txt");
   

3. Missing dependencies

   • Check CI logs for missing files
   • Ensure test data is committed to repo

Performance Issues

Slow build times

Solutions:

1. Disable virus scanning for build directories

   • Exclude project directory
   • Exclude .nuke, bin, obj folders

2. Use incremental builds

   # Don't clean every time
   ./build.ps1  # Instead of ./build.ps1 Clean Compile
   

3. Close other applications

   • MSBuild is CPU/memory intensive
   • Close Visual Studio when using command line builds

4. Check disk I/O

   • Use SSD for source code
   • Consider RAM disk for temp files

High memory usage during build

MSBuild node reuse:

The build scripts disable node reuse for clean builds:

dotnet build /nodeReuse:false /p:UseSharedCompilation=false

For development, you can enable it for faster builds:

dotnet build Dalamud/Dalamud.csproj

Platform-Specific Issues

Windows

Long path errors

Error:

The specified path, file name, or both are too long

Solution: Enable long path support:

# Run as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Or clone to shorter path:

git clone https://github.com/goatcorp/Dalamud.git C:\dev\dal

Execution policy errors

Error:

build.ps1 cannot be loaded because running scripts is disabled

Solution:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
./build.ps1

Linux

Cannot build C++ components

Expected behavior: Linux builds skip native components.

The build system detects this and skips:

• CompileCImGui
• CompileCImPlot
• CompileCImGuizmo
• CompileDalamudBoot
• CompileDalamudCrashHandler

Only managed code (C#) is built on Linux.

Permission denied on build.sh

Error:

bash: ./build.sh: Permission denied

Solution:

chmod +x build.sh
./build.sh

Getting Help

Discord Server

Ask in #dev channel for development questions

GitHub Issues

Report bugs or search existing issues

Build Logs

Always include full build output when asking for help

System Info

Provide OS, .NET version, and Visual Studio version

Diagnostic Commands

Run these to gather information for bug reports:

# System info
dotnet --info

# SDK versions
dotnet --list-sdks

# Runtime versions
dotnet --list-runtimes

# MSBuild version
msbuild -version

# Git status
git status
git submodule status

# Build with verbose logging
./build.ps1 --verbosity detailed

Next Steps

Building Dalamud

Return to build instructions

Contributing

Learn how to contribute