Troubleshooting: Installation & Loading

Use this page if Ziva does not load or its panel is missing or blank. The main troubleshooting page explains how to find and export logs for support.

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.

Installer: “staged executable is not a stable Godot editor”

This error (GODOT_STAGED_EXECUTABLE_INVALID) means the installer could not verify the downloaded Godot editor. Try the latest installer and retry.

The Ziva add-on is installed before this Godot check. If you already have Godot 4.2 or newer, open the project in that editor instead of deleting the add-on.

To retry without downloading another Godot:

1. Turn off Launch Godot when complete.
2. Under Advanced options, turn off Download Godot if not found.
3. Install, then open the project in your existing Godot editor.

Turning off launch alone does not skip downloading or checking Godot.

“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. Only unblock files you trust from Ziva’s download page; do not bypass warnings for an unknown download.

1. If SmartScreen shows a warning when running the installer, click More info → Run anyway.
2. 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.
3. 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)

Ziva’s macOS plugin and installer are signed and notarized by Zivash, Inc. If macOS says the library “cannot be opened because the developer cannot be verified,” update to the latest Ziva first. Older versions weren’t notarized. If it still happens:

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

xattr -dr com.apple.quarantine /path/to/your/project/addons/ziva_agent

Linux

Only change permissions for a trusted Ziva download.

chmod -R u+x /path/to/your/project/addons/ziva_agent

The plugin panel is blank or white

Follow the steps for your operating system below.

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.

Windows - the panel stopped working after it had loaded

If the Ziva panel was working and then went blank or frozen, the WebView2 process that draws it may have closed unexpectedly. When the panel shows a Retry button, click it: Ziva starts a fresh copy of its screen without restarting Godot. If the panel stays blank with no button, restart Godot.

If this keeps happening, send a bug report so we can see why WebView2 closed.

Linux - the screen failed to start

Run Godot from a terminal and check *_gdext.log for messages mentioning CEF, such as CEF helper not found or Failed to initialize CEF. If you see one, export your logs and send them to support or Discord, along with your Linux version and the visible error. Review the logs for private information first.

macOS

If the panel is blank, check *_gdext.log for webview errors. If the problem persists, resetting Ziva may help, but resetting removes this project’s Ziva chats and settings. Export your logs before resetting.

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.
• If those checks do not help, resetting Ziva makes it set up the helpers again on next launch. This removes this project’s Ziva chats and settings. Export your logs before resetting.