| name | cocos-creator-cli-build-debug |
| description | Use when Cocos Creator 3.x CLI build fails with scene or library errors. |
Cocos Creator CLI Build Debug
Debug Cocos Creator 3.x CLI build failures — scene JSON corruption, library import errors, and resource missing errors.
Common CLI Build Errors
| Error | Likely Cause | Check |
|---|
| Error 1222/1223 | Scene JSON corrupt | python3 -c "import json; json.load(open('assets/scenes/MainScene.scene'))" |
resource.ac not found | Asset bundle missing | Check assets/bundle/ exists |
| Module import failed | TS compile error | Run npx tsc --noEmit |
| Library version mismatch | Cocos version conflict | Check package.json @cocos/creator version |
WeChat Mini Game (wechatgame) Known Issues
Cannot set property 'w' of undefined (2026-06-16)
- Symptom: Console shows
TypeError: Cannot set property 'w' of undefined at trt (virtual cc-XXX.js:2)
- Root cause: Cocos engine rendering pipeline initialization fail →
FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT in OpenGL framebuffer
- NOT fixed by: Disabling video/webview engine modules, delaying bootstrap init, or changing camera settings
- Status: Confirmed as Cocos 3.8.8 engine bug on WeChat mini game platform
- Workaround: Not found yet — needs Cocos official patch or engine config deep-dive
- Evidence: Bootstrapper mounts successfully, 7 menu buttons created, project starts — but black screen due to rendering pipeline fail
Build Performance
- First build with full engine modules: ~42 seconds
- After disabling unused modules: ~7 seconds
- Key modules to keep for 2D zen game: base, 2d, ui, graphics, gfx-webgl, animation, audio, tween, particle-2d
- Modules safe to disable: video, webview, 3d (if 2D only), physics-3d, gfx-webgpu
Scene Config Tips
project.json startScene must match the actual scene UUID
- Build uses
profiles/v2/packages/builder.json scenes[] list — all listed scenes get built
overwriteProjectSettings in builder.json can override engine module settings
- After changing engine.json modules, run a full rebuild (not incremental)
Build Command (CLI, no GUI needed)
/Applications/Cocos/Creator/3.8.8/CocosCreator.app/Contents/MacOS/CocosCreator --project . --build "platform=wechatgame"
Recovery Flow
- Fix any TS compile errors first
- If scene corrupt: restore from git or rebuild in Editor
- Clear library cache:
rm -rf library/
- Re-import assets: Open project in Cocos Creator (GUI)
See references/error-catalog.md for complete error code reference.