Troubleshooting

This page covers the tools you need to debug almost any Ziva issue: finding your logs, running Godot in verbose mode, and resetting Ziva to a clean state. The other troubleshooting pages reference these steps, so start here.

If you get stuck, join our Discord  and share your logs (see Collecting a bug report below).

Which page do I need?

Finding your logs

Ziva writes logs to the ziva/logs/ folder inside your Godot project’s user data directory. Each session produces:

• *_gdext.log — the loading log (starting up and showing Ziva’s screen)
• *_sidecar.log — the main Ziva log (chats, AI providers, sign-in)
• *_sidecar_piped.log — extra startup and crash output from the Ziva server, handy when it won’t start at all

Exporting logs in one click (easiest)

In the chat, type /export-logs and run it (it’s also available as Export Logs in the chat header menu). Ziva zips up the plugin server logs into a ziva-logs-<timestamp>.zip file and reveals it in your file explorer, so you can attach it to a bug report directly. This is the quickest way to gather logs for a bug report.

Opening the logs folder

Open Settings → About → Open Logs Folder. This opens the logs directory in your system file manager — useful when you want to read an individual log such as *_gdext.log.

Finding the folder manually

The logs live at user://ziva/logs/, which is in a different place on each operating system. Replace <project-name> with your Godot project’s name.

Windows

%APPDATA%\Godot\app_userdata\<project-name>\ziva\logs\

macOS

~/Library/Application Support/Godot/app_userdata/<project-name>/ziva/logs/

Linux

~/.local/share/godot/app_userdata/<project-name>/ziva/logs/

Running Godot in verbose mode

Verbose mode prints extra detail to the Godot console, including plugin loading errors that are otherwise easy to miss. Launch Godot from a terminal so you can see the output.

Windows (PowerShell)

& "C:\path\to\Godot.exe" --verbose --editor --path "C:\path\to\your\project"

macOS

/Applications/Godot.app/Contents/MacOS/Godot --verbose --editor --path "/path/to/your/project"

Linux

./Godot_v4.x --verbose --editor --path "/path/to/your/project"

Watch the terminal output while reproducing your issue. Lines mentioning ziva, GDExtension, or library are the most relevant.

Resetting Ziva to a clean state

Many issues are fixed by clearing Ziva’s saved data. This often clears up stuck logins, scrambled saved data, or problems after an update. This removes your settings, sign-in, and any stored API keys. A backup is made first.

From inside Ziva (recommended)

If the panel still loads, Ziva shows a recovery screen with a Clear Data & Restart button when something goes badly wrong. You can also trigger it from the error screen. It backs up your data, clears it, and restarts Godot.

Manually

If the panel won’t load at all, delete the ziva folder inside your project’s Godot user data directory (the same parent folder as your logs — see Finding the folder manually):

Windows (PowerShell)

Remove-Item -Recurse -Force "$env:APPDATA\Godot\app_userdata\<project-name>\ziva"

macOS

rm -rf ~/Library/Application\ Support/Godot/app_userdata/<project-name>/ziva

Linux

rm -rf ~/.local/share/godot/app_userdata/<project-name>/ziva

Restart Godot afterwards. Ziva re-downloads what it needs on next launch.

Collecting a bug report

When asking for help, include:

1. Your operating system and Godot version.
2. Your Ziva plugin version (Settings → About → Version).
3. Your logs — run /export-logs to get a zip in one click. For the native loading log, also grab the latest *_gdext.log from your logs folder.
4. Steps to reproduce, ideally captured with Godot running in verbose mode.