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/v1 instead 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:

  1. File > Build Settings
  2. Check "Development Build"
  3. 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