Linux Build Troubleshooting
Common issues and solutions when building Unity projects for Linux.
This guide covers common issues encountered when building and running Unity projects on Linux, along with their solutions.
Git LFS Files Not Downloading (Case Sensitivity)
Symptoms
- Textures appear as solid colors (pink, black, or corrupted)
- Materials show as magenta/pink (missing shader or texture)
- Asset files are only 130-150 bytes instead of their actual size
- Files contain text like
version https://git-lfs.github.com/spec/v1instead of binary data
Cause
Linux filesystems are case-sensitive, while Windows and macOS are typically case-insensitive. If your .gitattributes file specifies LFS tracking for *.tga but your actual files use .TGA (uppercase), Git LFS will not recognize them on Linux.
Diagnosis
Check if a file is an LFS pointer instead of actual content:
# Check file size - LFS pointers are ~130 bytes
ls -la Assets/Textures/SomeTexture.TGA
# Check file content - LFS pointers contain version header
head -c 50 Assets/Textures/SomeTexture.TGA
Check how many LFS files are still pointers:
git lfs ls-files | wc -l # Total LFS-tracked files
git lfs ls-files | grep "^-" | wc -l # Files still as pointers (not downloaded)
Solution
Add both lowercase and uppercase variants to .gitattributes:
# Images - both cases
*.tga filter=lfs diff=lfs merge=lfs -text
*.TGA filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
*.PNG filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.JPG filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text
*.PSD filter=lfs diff=lfs merge=lfs -text
*.exr filter=lfs diff=lfs merge=lfs -text
*.EXR filter=lfs diff=lfs merge=lfs -text
# Audio - both cases
*.mp3 filter=lfs diff=lfs merge=lfs -text
*.MP3 filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text
*.WAV filter=lfs diff=lfs merge=lfs -text
# 3D Models - both cases
*.fbx filter=lfs diff=lfs merge=lfs -text
*.FBX filter=lfs diff=lfs merge=lfs -text
# Fonts - both cases
*.ttf filter=lfs diff=lfs merge=lfs -text
*.TTF filter=lfs diff=lfs merge=lfs -text
*.otf filter=lfs diff=lfs merge=lfs -text
*.OTF filter=lfs diff=lfs merge=lfs -text
After updating .gitattributes, force Git to re-download the files:
git checkout HEAD -- .
# Or for specific directories:
git checkout HEAD -- Assets/Textures/
Shader Compilation Errors: "Unexpected token 'const'"
Symptoms
Shader error in 'ShaderName': 'const': unexpected token at line X
Cause
Some Unity shader compilers do not support the const keyword in function parameter declarations within HLSL/CG shaders.
Example of Problematic Code
float4 MyFunction(const float4 param1, const int param2)
{
// ...
}
Solution
Remove const from function parameters:
float4 MyFunction(float4 param1, int param2)
{
// ...
}
Finding Affected Files
grep -r "const float\|const int\|const half" --include="*.shader" --include="*.hlsl" Assets/
Vulkan Shader Warmup Crashes
Symptoms
- SIGSEGV crash during game startup
- Crash occurs in
vk::OnscreenSwapChain::AcquireNextImage - Stack trace shows
ShaderVariantCollection.WarmUp()in the call chain - Crash happens in batchmode or when no display is available
Cause
Unity's ShaderVariantCollection.WarmUp() on Vulkan requires a valid display/swapchain. When running in batchmode (headless) or without a display, Vulkan cannot create the required swapchain, causing a crash.
Solution
Skip shader warmup on Linux builds:
private void PreWarm()
{
#if UNITY_STANDALONE_LINUX
// Skip shader warmup on Linux - Vulkan shader warmup crashes without a valid display
return;
#endif
if (shaderVariants != null)
{
shaderVariants.WarmUp();
}
}
Alternative: Check for Batchmode
If you want shader warmup on Linux with a display but not in batchmode:
private void PreWarm()
{
#if UNITY_STANDALONE_LINUX
if (Application.isBatchMode)
{
Debug.Log("Skipping shader warmup in batchmode");
return;
}
#endif
if (shaderVariants != null)
{
shaderVariants.WarmUp();
}
}
General Linux Build Tips
File Path Case Sensitivity
Linux is case-sensitive. Assets/Textures/Player.png and Assets/Textures/player.png are different files. Ensure all asset references in code and Unity match the actual file casing.
Line Endings
Ensure shell scripts and text files use Unix line endings (LF, not CRLF):
# Convert a file
sed -i 's/\r$//' script.sh
# Check for Windows line endings
file script.sh
Executable Permissions
Linux requires explicit executable permissions on scripts:
chmod +x BuildScripts/*.sh
Development Build for Debugging
Always create a development build first when debugging crashes:
- Enables full stack traces
- Shows managed code in crash logs
- Allows attaching debuggers
To create a development build:
- File > Build Settings
- Check "Development Build"
- Build and run
Testing Without Display (Batchmode)
Test headless/server builds locally:
./YourGame.x86_64 -batchmode -nographics
Quick Reference
| Issue | Symptom | Fix |
|---|---|---|
| LFS case sensitivity | Pink textures, tiny files | Add uppercase variants to .gitattributes |
| Shader const error | Compilation fails with "unexpected token" | Remove const from function parameters |
| Vulkan warmup crash | SIGSEGV at startup | Skip WarmUp() on Linux |
