Last updated August 28, 2026

Cocos Development Troubleshooting

Common failures when adapting a Cocos project for TikTok mini games, and where to look first. For failures that are not Cocos-specific, refer to the development troubleshooting guide and mini games error code reference.

Common failure points

Failure point	Common symptom	Check first
Base output	The game cannot open in DevTool or is stuck during startup.	Entry file, first scene, script loading order, and whether the package still depends on a regular HTML entry.
Resource loading	Local development works, but real-device preview misses images, audio, or gets stuck.	Path case, subpackage configuration, first-screen resources, remote resource domains, and CDN availability.
Platform capabilities	Calls do not work in Cocos Creator, or real-device preview fails.	Whether the environment provides real TikTok runtime, test user permission, app configuration, and game server flow.

Symptom: All you have before upload is a web directory, an H5 archive, or a standard web build output.
Cause: Mini games require a package the mini game runtime can load. A standard web entry cannot serve as a mini game package entry.
Solution: Reorganize the project into a Cocos game project with a stable build pipeline, then adapt the entry, package structure, and resource loading as described in the Cocos adaptation guide.

Symptom: TikTok mini games do not appear in the Cocos Creator build target list.
Cause: There is no TikTok build target for Cocos. Adaptation is manual.
Solution: Generate the build output closest to a mini game runtime, then adapt the entry, package structure, resources, configuration, and capability calls yourself. Keep those changes in project configuration or a build script so they survive the next build.

Symptom: Login, IAAs, IAPs, and other capabilities return no real result in the editor or your local environment.
Cause: Neither Cocos Creator nor your local environment provides the TikTok runtime.
Solution: Use simulated results to build out UI and business branches during development. Validate real behavior in DevTool, then on a real device inside the TikTok app.

Symptom: The game starts, but images, audio, scenes, or asset bundles fail to load.
Cause: Usually resource paths, path case, subpackage configuration, remote resource domains, or CDN access.
Solution: Confirm first-scene resources are in the main package. Then check the path case, subpackage roots, your configured trusted domains, and remote resource access.

Symptom: The game runs in Cocos but fails in DevTool or in real-device preview.
Cause: Real-device preview additionally checks TikTok app version, test user permissions, account region, platform configuration, package size limits, and real runtime behavior.
Solution: Record the package version, Cocos version, DevTool version, TikTok app version, device, region, and test user, then work through each of those in turn.

Symptom: Upload or pre-check reports that the total package, main package, subpackage, or independent subpackage exceeds its limit.
Cause: Too many first-package resources, duplicated or unused resources, remote resource strategy, or subpackage configuration.
Solution: Confirm the current limits, then work through resource compression, subpackaging, remote resources, and first-package contents. Address size early as it is expensive to fix immediately before review.

Was this document helpful?