Troubleshooting: Installation & Loading

Problems that stop Ziva from loading or showing up at all. If you haven’t yet, read the main troubleshooting page for how to find your logs and run Godot in verbose mode — both help diagnose everything below.

The Ziva panel doesn’t appear

If there’s no Ziva tab in the editor after installing:

Make sure you’re on Godot 4.2 or newer. Older versions can’t load the extension.
Confirm the plugin files are at addons/ziva_agent/ in your project and that the .gdextension file is present.
Download the build that matches your machine’s architecture (for example Apple Silicon vs Intel on macOS, or arm64 vs x64 on Windows/Linux). A mismatched architecture silently fails to load.
Restart Godot, then check the latest *_gdext.log and the verbose console for lines mentioning GDExtension or library.

”Failed to load” / blocked native library

Ziva ships a native library (.dll on Windows, .dylib on macOS, .so on Linux). Operating systems sometimes block libraries downloaded from the internet. The fixes are OS-specific.

Windows (Defender / SmartScreen)

Windows may quarantine or block the downloaded files.

If SmartScreen shows a warning when running the installer, click More info → Run anyway.
To unblock the plugin files: right-click the downloaded zip before extracting → Properties → on the General tab, tick Unblock → Apply. Then extract and copy the files. Unblocking the zip first unblocks everything inside it.
If antivirus removed or is blocking the .dll, add the plugin folder (your project’s addons/ziva_agent/) to your antivirus exclusions and reinstall.

macOS (Gatekeeper / quarantine)

macOS marks downloaded files as quarantined and may say the library “cannot be opened because the developer cannot be verified.”

Privacy & Security: open System Settings → Privacy & Security, scroll to the message about the blocked Ziva item, and click Open Anyway / Allow Anyway. You may need to retry the action in Godot once afterwards.
Terminal (removes the quarantine flag): point this at your project’s plugin folder.
```
xattr -dr com.apple.quarantine /path/to/your/project/addons/ziva_agent
```

Linux

Run Godot from a terminal (see verbose mode) — the loader error usually names the missing system library or the reason the .so was rejected.
Make sure the plugin files kept their executable bit after extracting. Some archive tools and filesystems drop it:
```
chmod -R u+x /path/to/your/project/addons/ziva_agent
```

The plugin panel is blank or white

The native library loaded, but the part that draws Ziva’s screen isn’t showing. Ziva draws its screen differently on each platform, so the cause differs.

Windows — WebView2 runtime missing

Windows uses the Microsoft Edge WebView2 runtime. Windows 11 includes it, but some Windows 10 machines and stripped-down Windows setups don’t. Install the Evergreen WebView2 Runtime from Microsoft’s official download page, then restart Godot.

Linux — the screen failed to start

On Linux, the part that draws Ziva’s screen sometimes fails to start. Run Godot from a terminal and check the *_gdext.log; messages mentioning CEF (such as CEF subprocess helper not found or Failed to initialize CEF) confirm it. Try a different GPU/driver setup, launch from a terminal so the error is visible, and share the log on Discord if it persists.

macOS

macOS uses the system WebView. If the panel is blank, check *_gdext.log for webview errors, then try resetting Ziva.

Tools or search aren’t working / missing bundled binaries

On first launch Ziva sets up a few small helper programs it needs (such as the search tool). If that setup fails, file-search and related tools won’t work.

OneDrive (Windows): projects or user folders synced through OneDrive can cause extraction failures. If possible, keep your Godot project and user data on a local (non-synced) path.
Make sure your antivirus isn’t deleting the unpacked binaries.
Resetting Ziva forces a clean re-extraction on next launch.