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.
On Windows and Linux, download the build that matches your machine’s architecture (arm64 vs x64). A mismatched architecture silently fails to load. The macOS build works on both Apple Silicon and Intel.
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, .framework 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 or out of date

Windows uses the Microsoft Edge WebView2 runtime. Windows 11 includes it, but some Windows 10 machines and stripped-down Windows setups don’t, and setups that block Microsoft updates can be stuck on a version too old for Ziva. Click Install WebView2 in the Ziva panel, run the installer, then click Retry.

Windows - “The webview failed to start (webview error -3)”

The Ziva panel shows this when WebView2 is installed but refuses to start. The message ends with the Windows error code WebView2 reported, so check that part first:

HRESULT 0x8007139F means another program is using WebView2 with the same data folder but different settings. This is usually another Godot editor started differently, for example from a launcher or with WebView2 environment variables set. Close the other editors, end every msedgewebview2.exe in Task Manager, then click Retry.
”… is a file, not a directory” or ”… is not writable” means WebView2 can’t use the data folder named in the message, which is under %APPDATA%. Move or rename the file at that path, or fix the folder’s permissions, then click Retry.

If the panel still won’t start, click Send report. The report includes your logs, which contain the full message.

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 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.