Heuristic:Zai org CogVideo Decord Import Order Bug
| Knowledge Sources | |
|---|---|
| Domains | Debugging, Dependencies, Video_Loading |
| Last Updated | 2026-02-10 02:00 GMT |
Overview
The `decord` video library must be imported AFTER `torch` to prevent segmentation faults. The `isort:skip` pragma prevents automatic reordering.
Description
The `decord` video decoding library has a known import-order bug where importing it before PyTorch can cause segmentation faults or stack smashing errors on certain system configurations. This is a rare but catastrophic failure that produces no helpful error message — just a crash. The CogVideoX codebase explicitly documents this with a comment and uses the `isort:skip` pragma to prevent code formatters from reordering the import.
Usage
Apply this heuristic when writing any Python code that uses both torch and decord in the CogVideoX project, or when debugging unexplained segfaults in data loading.
The Insight (Rule of Thumb)
- Action: Always import `torch` before `decord`.
- Value: Add `# isort:skip` after the decord import to prevent auto-reordering.
- Trade-off: None. This is a pure bugfix pattern with no downside.
Reasoning
From `finetune/datasets/utils.py:10-12`:
# Must import after torch because this can sometimes lead to a nasty
# segmentation fault, or stack smashing error
# Very few bug reports but it happens. Look in decord Github issues for more relevant information.
import decord # isort:skip
Same pattern in `finetune/datasets/i2v_dataset.py:28-30`:
# Must import after torch because this can sometimes lead to a nasty
# segmentation fault, or stack smashing error
import decord # isort:skip
The root cause is likely a conflict between decord's and torch's shared library loading (both use CUDA/C++ extensions). When decord loads its C extensions first, it can interfere with torch's CUDA runtime initialization.