Known Issues
Known limitations and workarounds for StructKit.
Performance
Large Directory Structures
Generation becomes slow with 1000+ files. Break structures into smaller modules and use --dry-run to preview first.
Remote File Fetching
Sequential processing of many remote files can be slow. Cache frequently used files locally.
Template Engine
Complex Jinja2 Expressions
Very complex expressions may not render correctly. Break into simpler parts using intermediate variables.
Unicode in File Names
May cause issues on some filesystems. Use ASCII-safe file names.
Platform-Specific
Windows Path Handling
Long path names may exceed the 260-character limit. Enable long path support in Windows 10/11.
macOS Case Sensitivity
Case-insensitive filesystem can cause conflicts. Ensure file names differ by more than just case.
GitHub / Docker
GitHub API Rate Limiting
Set GITHUB_TOKEN environment variable for higher limits.
Docker File Permissions
Use -u $(id -u):$(id -g) when running Docker to fix ownership.
Limitations
- Variables in nested structures don't propagate back to parent structures (by design)
- Circular references in variable definitions are not detected
- File operations are not atomic — use
--backupfor important operations - Symbolic links are not explicitly handled
- Very large YAML files (>10MB) may cause performance issues