Troubleshooting

This page covers problems people run into with Zornov and how to fix them. If yours isn't here, press F1 in Zornov and search the help, or ask in GitHub Discussions.

Zornov won't open

Mac: macOS asks before opening Zornov

The Mac app is signed and notarised. The first time you open it, macOS may say it was downloaded from the internet and ask whether to open it. Choose Open.

Zornov needs a Mac with Apple Silicon (M1 or later) and macOS 13 or later. It doesn't run on Intel Macs.

Windows: "Windows protected your PC"

Windows SmartScreen can show this for a program it hasn't seen often. Choose More info, then Run anyway.

Windows: the window never appears

• If you use the portable zip, check that zornov.exe is still in the folder you extracted, next to zornov-cli.exe, dxcompiler.dll and dxil.dll. Zornov needs these files beside it to draw with DirectX 12. Extract the zip again if any are missing.
• Update your graphics driver from your computer maker or your graphics card maker.
• Look for a crash report in %LOCALAPPDATA%\Zornov\crashes, and in Event Viewer under Windows Logs > Application (look for an Application Error entry). Attach what you find when you report the problem.

Linux: nothing happens, or an error about a library

Start the editor from a terminal to see the error, with --window after the program:

zornov --window                          # the .deb
./Zornov-0.1.2-x86_64.AppImage --window  # the AppImage
./zornov --window                        # in the archive's folder

If the AppImage doesn't start when you double-click it, make it executable: open its properties in your file manager and allow it to run as a program, or run chmod +x on it.

Zornov draws with Vulkan on Linux. If the window doesn't appear, check that your graphics driver has Vulkan support installed (on Ubuntu and Debian, mesa-vulkan-drivers for Intel and AMD graphics).

Linux: typing zornov gives a prompt, not the window

That's expected. In a terminal, zornov starts Zornov's command prompt. To open the editor window, run zornov app, or start Zornov from your applications menu.

Playback and graphics

Playback stutters or drops frames

Try these, one at a time:

1. Lower the preview quality. Use the quality menu in the Viewer, or Settings > Playback > Preview quality, and choose Half or Quarter. This changes only the preview, not your export. Zornov never lowers it by itself.
2. Give Zornov more memory for frames: raise Settings > Playback > Frame cache. This helps most on long projects.
3. Switch Settings > Playback > Preview engine to Simple. It draws each clip on its own and is lighter on older computers.

A file won't import or play

Zornov converts files it can't play directly, in the background, and adds them when they are ready. Watch the bell button in the top bar for the job's progress.

If Zornov says "Could not import" and the file's name, the file may be damaged or in a format Zornov can't read. See Import and export formats.

Sound

No sound when playing

1. Check that the lane isn't muted. Each lane has a speaker button at its left; a crossed-out speaker means the lane is muted.
2. Check the clip's volume in the Inspector's Audio tab.
3. Zornov plays through your system's default sound output (Settings > Playback > Audio output shows System default). Pick the speakers or headphones you want in your system's sound settings. If you change the output while Zornov is open and the sound doesn't follow, quit and reopen Zornov.

Mac: recording finds no microphone or camera

macOS asks for permission the first time you press Record. If you chose not to allow it, open System Settings > Privacy & Security, choose Microphone (or Camera), and turn on Zornov.

The content library won't download

The Assets and Audio sections of the Library offer Download the library, about 280 MB. If it fails, the panel says "The library did not download" and why. Check your internet connection and click Try again.

Updates

"This copy cannot update itself"

Zornov tells you about new versions, but some copies can't replace their own files: a Linux .deb install, a Mac copy running from the disk image, or a portable folder or AppImage in a place you can't write to. See Installs that can't update themselves.

"The update did not work"

Your current version is left as it was. Click Try again. You can also check from Help > Check for updates… or Settings > About.

The AI editor

The AI editor shows "Meet the AI editor" and won't answer

The AI editor is off until you turn it on. Click Turn on the AI editor, or go to Settings > AI and switch on AI editor on under What is sent.

The AI editor can't connect

Go to Settings > AI and check Answered by:

• Claude API or OpenAI API needs an API key. Paste it in API key and click Save. Get a Claude key from console.anthropic.com or an OpenAI key from platform.openai.com.
• Claude Code or Codex uses the sign-in of that program, which must be installed on this computer. If it isn't, the note under Model says so and shows the command to install it. For Codex, also run codex login once in a terminal.

AI assistants (Claude Code, Claude Desktop, Codex)

Every assistant setup starts the Zornov you installed, so install Zornov first.

The assistant can't find Zornov

Claude Code's plugin, Codex and most other assistants run zornov by name, so it must be on your PATH. Test it in a terminal:

zornov --help

On Windows, use zornov-cli --help. If the command isn't found:

After changing your PATH or the assistant's settings, restart the assistant.

Claude Desktop: the Zornov extension doesn't start

The extension (Zornov.mcpb) starts Zornov from its usual place: /Applications/Zornov.app on a Mac, or C:\Program Files\Zornov (the installer) on Windows. If you put Zornov somewhere else, or use the portable zip, set Zornov up in Claude Desktop's configuration with the full path instead. See Use Zornov from Claude, Codex and other AI assistants.

I can't see the assistant's edits in the window

The assistant edits the project you, or it, chose. To watch each edit happen, open that same project folder in the Zornov window. If you gave the assistant a project with --project, open that folder with File > Open….

Report a problem

If you can't fix it, open an issue at github.com/zornov/zornov/issues. Include:

• your Zornov version (shown in Settings > About) and your operating system
• what you did, what you expected and what happened instead
• any crash report

Zornov saves a crash report on your computer when it quits unexpectedly. Reports hold the version, your system and a technical trace, and no projects or files. Find them in Settings > About > Crash reports > Show reports folder.