Troubleshooting

The site preview can’t find pnpm or npm

The preview runs your project’s own dev server, so it needs Node.js and your project’s package manager. Writing and publishing don’t.

1. Open a terminal and run pnpm --version, or npm --version for an npm project.
2. If it works there, quit Zeku completely and open it again. Zeku reads the terminal’s PATH when it starts, so a package manager installed while Zeku was open isn’t seen until then.
3. If it doesn’t work in the terminal either, install Node.js and your package manager first. On a Mac with Homebrew, that’s brew install node pnpm.

Then install your project’s dependencies once, with pnpm install or npm install in the project folder.

macOS says it can’t verify Zeku

The .dmg isn’t notarized by Apple yet. Install with the command instead, which avoids the check entirely:

curl -fsSL https://zeku.dev/install.sh | bash

Or open System Settings > Privacy & Security and click Open Anyway. See Install Zeku.

Linux

The AppImage doesn’t start. The one-line install sets it up to run without FUSE. If you downloaded the AppImage by hand, run it with --appimage-extract-and-run, or install fuse3 from your package manager.

The window is blank. Zeku already turns off the WebKitGTK renderer that shows a blank window on some NVIDIA drivers. If yours is still blank, start Zeku from a terminal with zeku and send the output to hello@zeku.dev.

Everything is too big or too small. Zeku runs natively on Wayland and follows your desktop’s scale. To run it through X11 instead, start it with GDK_BACKEND=x11 zeku.

You want your desktop’s title bar. Turn on Settings > Features > System title bar.

Publish or pull fails

Zeku says why in plain words. The two most common:

• Git couldn’t sign in. Sign in to your git host once in a terminal, or with your git credential manager, and try again.
• Signed in, but no access. The account git uses can’t push to this repository. Sign in as an account that can.

See Publish and pull.

Fields look wrong, or a collection is missing

Zeku reads your field types from the schemas Astro generates. In your project folder, run astro sync, then run Re-learn project model from Zeku’s command palette. If a collection is still missing, check that it’s defined in src/content.config.ts. See How Zeku reads your site.

Zeku closed unexpectedly

Open it again. Unsaved changes are kept as you type and come back when you reopen the project.

Note

Still stuck? Email hello@zeku.dev with what you did, what you expected, and what happened.