11. Troubleshooting

Before anything else: if you have a problem with KaKeKiKoKu, ask your connected AI to run help kakekikoku for the product and Web app guide, or help for the complete command-topic index. You can also give it the URL of kakekikoku.com for current public information. Your AI can probably guide you better than any manual, because it has access to your project's context and KaKeKiKoKu's documentation at the same time.

A sidecar seems corrupt or unreadable

A sidecar's content displays incorrectly or KaKeKiKoKu reports problems reading it.

KaKeKiKoKu is forgiving: when it finds a corrupt file, it tries to recover as much as it can rather than rejecting it completely. In many cases, the content will display partially.

What to do: run a sync first, then ask your AI to help recover the damaged context. KaKeKiKoKu gives connected AIs specific guidance for corrupted .wuniq files, so they can often rescue useful knowledge and recreate a valid context through KaKeKiKoKu.

  • Prefer recovery through KaKeKiKoKu. The safest path is usually to create a clean context and move the recovered knowledge into it, then run sync again.
  • Do not hand-edit .wuniq files casually. Direct edits can make recovery harder. If manual repair is truly necessary, let the AI explain the step and keep a backup.

You can say: "KaKeKiKoKu reports that this context is corrupt. Run sync, inspect it safely, and recover whatever knowledge can be recovered."

A Git conflict blocks a KaKeKiKoKu context

If the right-hand issue panel shows Git conflicts in KaKeKiKoKu contexts, a .wuniq file still contains a complete merge-conflict block. KaKeKiKoKu blocks normal synchronization for that project rather than treating both alternatives as reliable knowledge. The context is temporarily absent from the navigation tree and search; this is intentional.

What to do: click the 🤖 button on the conflict row, or ask your AI to repair the exact file shown. The AI receives the KaKeKiKoKu format guidance and instructions to preserve the UUID, private fields, sections, relations, and non-conflicting knowledge. If the merge intent is ambiguous, it should ask you instead of guessing.

  • Do not acknowledge, dismiss, or exclude the issue. It disappears only when every complete conflict block has been resolved.
  • KaKeKiKoKu and the AI do not stage or commit the result unless you explicitly ask.
  • Run Analyze again after the repair. Normal project validation resumes and the context returns to navigation.

See Git conflicts in the Sync & Issues panel for the UI behavior.

Very large project and KaKeKiKoKu is slow

If your project has thousands of files and KaKeKiKoKu takes a long time to sync.

Solutions:

  • Check exclusions. Are you excluding node_modules/, bin/, dist/ and other heavy folders? Go to Settings > Project > Exclusions.
  • Consider splitting into multiple projects. If your project is truly enormous, you can create several KaKeKiKoKu projects for areas that make conceptual sense. Keep in mind that you won't be able to establish direct relationships between different projects, but your AI can work with all of them if they're open.
  • Never place a KaKeKiKoKu project inside another. The inner project would be treated as part of the outer one.

KaKeKiKoKu closes when your AI client closes — or vanishes right after starting

If KaKeKiKoKu isn't running when your AI client connects, the client starts it automatically through MCP. Convenient — but it ties KaKeKiKoKu's lifetime to that client: when the client shuts down its MCP servers (on exit, or in some IDEs even shortly after startup, while no chat is open yet), the operating system may take KaKeKiKoKu down with them. Whether this happens depends on the client and the platform, which is why it can look intermittent.

The stable setup: start KaKeKiKoKu yourself, before your AI client. Launch it from the Start menu on Windows or the applications menu on Linux. Started that way, KaKeKiKoKu's lifetime doesn't depend on any AI IDE — it stays up until you exit it, and AI clients simply connect to the instance that's already running. No duplicates to worry about: clients never start a second KaKeKiKoKu.

KaKeKiKoKu on Linux

KaKeKiKoKu runs on Linux as a Snap package. A few behaviors are specific to that platform — if something seems off on Linux, check here first.

  • Changes in mounted folders aren't detected. On shared or network mounts (VMware vmhgfs, CIFS/SMB) the Linux kernel emits no file-change events, so automatic drift detection won't fire. Use manual sync or the Analyze button. Projects under your home directory work normally.
  • Projects outside your home directory. The Snap runs under strict confinement and has no access to /mnt, /media or USB drives by default. Grant it once with: 
    sudo snap connect wuniq:removable-media
  • A huge project exhausts the file-watch limit. Linux caps the number of files that can be watched. For very large projects, raise it by adding fs.inotify.max_user_watches to /etc/sysctl.conf.
  • Closing your AI client also closes KaKeKiKoKu. On Linux the AI client, KaKeKiKoKu and its browser tab share a process group, so the advice above applies with extra force: launch KaKeKiKoKu from the applications menu before opening your AI client, and it will keep running across AI restarts.
  • Linux Mint: Snap support is disabled by default. Mint ships with snapd blocked. Remove the APT block that disables Snap and install snapd before installing KaKeKiKoKu.

Support

If after consulting this guide and asking your AI for help you still have problems, you can contact us through kakekikoku.com.

Important: free support is offered exclusively for real technical problems with the product — errors, failures, unexpected behavior. I cannot handle general usage questions (that's what this manual and your AI are for).

For enterprises: if your organization needs direct support, guaranteed response times, or deployment assistance, I offer annual support licenses. Request a quote through the website.