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.

Check that it works

Studio gives you access to the functional checks used before publishing a version. Running them is optional: you do not need to do it to use Studio or as routine maintenance. A successful result confirms the applicable checks in that environment; you can still report a problem you have noticed.

Choose Help > Check that it works, or the link on the welcome screen. This opens the results page without starting a run. Choose Start the check to see the notice, then confirm when convenient.

Before starting

Save your work and leave Studio unused until it finishes. The check can take tens of minutes. It temporarily closes your open projects, pauses AI connections and other Studio tabs, and opens the projects again afterwards. An unsaved draft prevents it from starting. Connected AIs need to open and read their projects again after the check.

The notice shows the exact location inside your working directory: KaKeKiKoKu Studio Self-Check/run-…. Each run uses a new folder and artificial projects. Your project files are not modified. Use a working directory on a native local filesystem, with enough free space; a folder shared with another operating system can behave differently and give misleading filesystem results.

The Windows check uses the installed Microsoft Edge, with its own temporary browser profile, even if you use Studio in another browser. The installed Linux Snap runs MCP/HTTP and support checks without a browser; its report says Web: not included in the Snap package. A missing required dependency produces an incomplete result. Checking the Web on Linux is a development workflow and requires a non-Snap Chromium browser in PATH (Microsoft Edge, Google Chrome or Chromium); Firefox is not supported by the test controller.

Results and cancellation

• Passed: all applicable checks completed successfully. No report is needed.
• Failed: a check detected a problem. The page identifies the first problem and keeps the run's evidence.
• Incomplete: the planned checks could not all be completed. Read the stated cause; this is neither a pass nor, by itself, proof of a product fault.
• Cancelled or interrupted: the run did not finish. You can start a new check when convenient.
• Not started: a precondition prevented the run. Resolve the reason shown before starting again.

Not applicable means that an individual check does not apply to this run's conditions, for example the operating system or connected tabs. It is not counted as passed. Not run means a planned check did not take place. The summary gives the reasons and the scope of the run.

You can cancel from the progress page. Cancellation waits for the current step to answer before restoring your projects. If Studio stops unexpectedly, the next start reports the interruption; use Reopen previous projects to recover the projects that have not yet been reopened.

Save evidence for support

A successful run removes its own folder and keeps the summary. Other results keep the folder. From the results page you can open a retained folder, save its ZIP for support, or delete a retained run when you no longer need its evidence.

Save ZIP for support writes to your Downloads folder and shows the exact path. It contains the summary, a reduced technical diagnostic, log, evidence and artificial test data, with a file manifest. It does not include your projects' contents. Saving the ZIP does not send it.

If you have detected an error, email the ZIP to support@kakekikoku.com. Explain what you were trying to do, what you expected and what happened; include reproduction steps if possible. You can also report an observed problem when the check passes.

Run from a terminal on Linux

On Windows, start the check from Help or the welcome screen. The Microsoft Store package has no terminal command for the check.

The Linux Snap also provides a terminal command that uses the same check as the interface:

wuniq.check

It accepts --help, --yes to start without an interactive confirmation, and --zip to save a support ZIP when the run leaves its folder on disk. Ctrl+C requests cancellation. A development pass does not validate the installed Snap command.

A context seems corrupt or unreadable

A context'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, untrack, 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

With the instruction-file HTTP connection, always start Studio first and keep it running. After a port change, update the address in the file. For connection refused, permissions, or remote execution, see the common connection guide.

MCP discovery and local help do not start the application. The first command that needs the Knowledge Engine starts or reuses it. Closing an MCP connection does not itself request application shutdown, but a client or operating system that terminates a whole process tree can still end a child application. Record the client, operating system, versions, and the action that triggers the disappearance before attributing a cause.

Start KaKeKiKoKu independently. Launch it from the Start menu on Windows or the applications menu on Linux before opening your AI client. This also lets you use the knowledge workspace without an AI. If the application still disappears, check that you have the current release and save a diagnostic report from Help for your bug report. Reopening a browser tab alone does not restart a stopped application.

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. Some shared or network mounts do not deliver reliable file-change events. KaKeKiKoKu uses fallback polling as well as the file watcher; detection can therefore take longer. Check the polling interval in Settings, or use Analyze or ask your AI to run sync.
• Projects on mounted or removable storage. The Snap runs under strict confinement and has no access to /mnt, /media, or /run/media by default. Grant it once with:

  sudo snap connect wuniq:removable-media

  This grants access to those mount locations; it does not unlock every path outside your home directory.
• 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.
• Application lifetime. The Linux launcher detaches its session to reduce terminal-close signals. A cgroup or an explicit process-tree termination can still stop it. Use the independent launch described above and report reproducible failures with the client and distribution versions.
• 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 you still have a technical problem, contact support@kakekikoku.com. The functional check can help collect evidence without sharing your projects. For startup or connection problems, Help > Save Diagnostic Report provides a separate report about infrastructure and configuration.

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).