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 appearCopy Anchor Link

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"Copy Anchor Link

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 libraryCopy Anchor Link

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)Copy Anchor Link

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)Copy Anchor Link

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

LinuxCopy Anchor Link

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 whiteCopy Anchor Link

"Ziva's interface failed to start"Copy Anchor Link

Ziva draws its panel with a built-in browser that it downloads with its tools. On macOS the panel needs macOS 12 (Monterey) or newer.

• "Too many editors are open": close one of your other Godot editors, then click Retry.
• Anything else: restart Godot. If the panel still won't start, click Send report. The report includes your logs, which contain the full message.

The panel stopped working after it had loadedCopy Anchor Link

If the Ziva panel was working and then went blank or frozen, Ziva restarts its screen on its own. If the panel says Ziva's panel keeps crashing, click Retry. If it keeps happening, send a bug report.

On Windows, logs include memory usage sampled every 30 seconds and when Ziva's background service exits. These are numeric system and process measurements, not memory dumps or screen contents.

Linux - the screen failed to startCopy Anchor Link

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.

macOSCopy Anchor Link

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.

"Ziva couldn't download its tools" / "Ziva couldn't finish setting up"Copy Anchor Link

The first time you open each Ziva version, it downloads its tools for your computer. The panel names the problem and offers Retry:

• Couldn't connect or download stopped partway: check your internet connection, and that a firewall, proxy or VPN allows ziva.sh and downloads.ziva.sh. Then click Retry.
• Download was blocked: allow those same sites in your firewall, proxy or VPN, then click Retry.
• Couldn't make a secure connection: on public Wi-Fi, sign in to the network first. Otherwise check that your computer's date and time are correct, and that no proxy or antivirus inspects secure connections. Then click Retry.
• Too many downloads or download server had a problem: wait a few minutes, then click Retry.
• Files from different versions: click Repair Ziva. Godot restarts; your chats and settings stay.
• Tools aren't available to download yet: wait a few minutes, then click Retry. If it keeps happening, reinstall Ziva.
• Download was damaged: click Retry. If it keeps happening, a proxy or security tool may be changing downloads.
• Couldn't save its tools: free up disk space or allow Ziva in your antivirus, then click Retry.

If antivirus later removes Ziva's main program, Ziva downloads its tools again the next time it starts.

Tools or search aren't working / missing bundled binariesCopy Anchor Link

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.