Troubleshooting

Troubleshooting is the standard diagnostic path for Zipoly compression/conversion issues: run the built-in tool diagnostics first, match the result against the solutions below, and if nothing helps send support the checklist at the bottom. 90% of compression failures are caused by the missing VC++ runtime — check that first.

The path: Settings → Tool Diagnostics → Run Diagnostics → match the result to a fix below.

Symptom Lookup

Symptom	Most likely cause	Jump to
✗ Cannot execute / VCRUNTIME140.dll not found	Missing VC++ runtime	Runtime missing
✗ Not found / ⚠ No response	Tool files missing or corrupted	Tool files
✗ Cannot execute with runtime installed	Blocked by antivirus	Antivirus
Linux launch failure	webkit2gtk/gtk3 missing	Linux deps
macOS "cannot verify developer"	Gatekeeper block	Gatekeeper
"Already Draco compressed" message	Recompressing a compressed file	Use the original file — see FAQ

Missing Visual C++ Runtime (most common)

Symptoms: diagnostics show ✗ Cannot execute, or a "VCRUNTIME140.dll not found" error.

Cause: Windows is missing the Microsoft Visual C++ 2015-2022 Redistributable (x64), a required component of the compression engines. 90% of compression failures are caused by this.

Fix:

1. Download the VC++ runtime
2. After installing, reopen Zipoly (no system restart needed)

Tool Files Missing or Corrupted

Symptoms: ✗ Executable not found or ⚠ No response.

Fix: Reinstall Zipoly. Don't download draco_transcoder.exe or gltfpack.exe separately to replace them — version mismatches may occur.

Blocked by Antivirus

Symptoms: diagnostics show ✗ Cannot execute even though the VC++ runtime is installed.

Fix: Add the Zipoly install directory (C:\Program Files\Zipoly\) to your antivirus whitelist/exclusion list.

Missing Linux Dependencies

Symptoms: Zipoly fails to start or features are unavailable on Linux.

Fix:

# Ubuntu / Debian
sudo apt-get install libwebkit2gtk-4.1-0 libgtk-3-0

# Fedora / RedHat
sudo dnf install webkit2gtk4.1 gtk3

macOS Gatekeeper Block

Symptoms: macOS shows "cannot verify the developer" or "damaged and cannot be opened" on first launch.

Cause: macOS Gatekeeper blocks unsigned/unnotarized apps by default.

Fix: Right-click Zipoly.app → choose Open (or go to System Settings → Privacy & Security → Open Anyway). Code signing and notarization are planned for a future release.

Advanced Troubleshooting

View detailed logs

In the diagnostics window, click "View Raw Output" → "Copy Result" and send the report to support.

Verify the tools manually

cd "C:\Program Files\Zipoly"
draco_transcoder.exe

You should see usage help (Usage: ...). If it reports VCRUNTIME140.dll, the VC++ runtime is missing.

Technical Support

If none of the above helps, contact QQ 2162788746 with the following to speed up the diagnosis:

1. The diagnostics report (get it via "Copy Result")
2. System version (Win + R → winver)
3. Zipoly version (top of the Settings page)

FAQ

Diagnostics are all ✓, but compression still fails?

Check the file itself: Draco-compressed files cannot be compressed again (start from the original uncompressed file); very small models (< 100KB) or very simple ones (< 1,000 faces) gain nothing from compression — skip it. If it still fails, use "View Raw Output" → "Copy Result" and send us the report.

Can a failed compression corrupt my original file?

No. Output is written to a new file with the _optimized suffix — the original is never overwritten; on failure just delete the output and retry.

Does macOS also need the VC++ runtime?

No. The missing VC++ runtime is a Windows-only issue. The common macOS issue is a Gatekeeper block and the common Linux issue is missing dependencies — see the matching sections above.

Reinstalled Zipoly but the tools are still broken?

Make sure you installed the complete package from the official site or Gitee Release (never replace tool files like draco_transcoder.exe individually), and run the Windows version as administrator once after installing. Still broken? Contact support with the diagnostics report.