trellis2.comtrellis2.com

TRELLIS.2 Errors and Fixes: Verified Troubleshooting Checklist

Mar 24, 2026

Most TRELLIS.2 local failures come from one of four boundaries: the wrong repository, an unsupported platform, an incomplete recursive clone, or a mismatch between the NVIDIA driver, CUDA Toolkit, PyTorch, and compiled extensions. Start with those facts before changing model code.

This checklist applies to microsoft/TRELLIS.2, not the older microsoft/TRELLIS repository.

First: confirm the supported environment

The upstream project currently documents:

  • Linux only
  • NVIDIA GPU with at least 24 GB memory
  • verification on A100 and H100
  • CUDA Toolkit required; 12.4 recommended
  • Python 3.8 or newer
  • Conda recommended

If you are using native Windows, macOS, AMD, Apple Silicon, or a lower-memory GPU, you are outside the documented support boundary. A community workaround may exist, but generic “fix” commands cannot make it an official configuration.

Repository or module files are missing

Typical symptoms

  • ModuleNotFoundError for project packages
  • missing o-voxel source
  • build scripts cannot find submodule files

Check

git remote -v
git submodule status

The remote should point to microsoft/TRELLIS.2, and the repository should have been cloned recursively.

Fix

git submodule update --init --recursive

Do not use installation commands written for microsoft/TRELLIS.

CUDA or PyTorch mismatch

Typical symptoms

  • torch.cuda.is_available() is false
  • extension compilation reports an unsupported CUDA version
  • runtime reports missing CUDA symbols

Check

nvidia-smi
echo "$CUDA_HOME"
nvcc --version
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

If several CUDA Toolkits are installed, choose the intended compiler explicitly:

export CUDA_HOME=/usr/local/cuda-12.4

Then recreate or repair the environment using the upstream setup.sh. Avoid mixing wheels and extensions compiled against different CUDA versions.

FlashAttention does not support the GPU

The official README notes that some GPUs, including V100, do not support the default FlashAttention path. The documented alternative is to install xformers and set:

export ATTN_BACKEND=xformers

Treat this as an attention-backend substitution, not a general fix for insufficient GPU memory.

O-Voxel, CuMesh, or rendering extension fails to import

Test components individually:

python -c "import o_voxel; print('o-voxel ready')"
python -c "import torch; print(torch.cuda.is_available())"

If an extension fails:

  1. confirm CUDA_HOME
  2. confirm the active Conda environment
  3. remove only that extension's failed build artifacts
  4. rerun the corresponding setup.sh flag

Do not delete the entire home-directory cache or use broad recursive deletion commands from an unverified troubleshooting post.

CUDA out of memory

First confirm that the GPU meets the upstream 24 GB requirement. Close unrelated GPU workloads and inspect actual memory use:

nvidia-smi

The official minimal example sets:

import os
os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"

This may reduce allocator fragmentation, but it does not turn an unsupported low-memory GPU into a supported configuration. The upstream project does not document CPU inference as a practical fallback.

Model weights do not load

Confirm that the model identifier is exactly:

microsoft/TRELLIS.2-4B

Then check network access, disk space, Hugging Face authentication if required by the current model card, and whether a partial cache download is being reused. Do not substitute the original TRELLIS checkpoints.

Official model source: Microsoft TRELLIS.2-4B.

GLB exports but transparency is missing

The upstream example exports GLB in OPAQUE mode by default. The alpha channel remains in the texture, but it is not active automatically. In Blender or another DCC, connect the texture alpha channel to the material opacity/alpha input and choose the appropriate blend mode.

This is documented behavior, not necessarily a failed generation.

Browser generator errors

For trellis2.com, collect:

  • the task ID
  • selected model and resolution
  • source image format and dimensions
  • exact visible error
  • whether credits were deducted

Do not assume a browser timeout means the provider failed or that credits were permanently lost. Check the task history first, then contact hello@trellis2.com with the task ID.

trellis2.com

trellis2.com