Troubleshoot

Get help with Kin.

If something fails or an answer looks wrong, tell us what you tried and what happened. Kin is a public alpha. Use the report template below, and keep private code and credentials out of public reports.

How this works in Kin

Kin is a public alpha, so rough edges are expected and worth reporting. A report that carries the four commands below is one a maintainer can act on; a report without them is a conversation about what you might have run.

Current release

v0.7.19. Kin is pre-1.0, so expect breaking changes. Check what you are on with kin --version before reporting anything, because a fixed problem and a live one read the same from the outside.

Where to ask

Issues
github.com/firelock-ai/kin/issues
A wrong answer, a crash, a refusal you did not expect. Bring the kin doctor output; it is the best diagnosis Kin has of itself.
Discussions
github.com/firelock-ai/kin/discussions
How to use it, whether it fits your repository, and what a result means. An answer that surprised you is a good discussion before it is a good issue.
Security
github.com/firelock-ai/kin/security/policy
Private vulnerability reporting is enabled on the repository. Do not open a public issue for a security finding.

The diagnostic bundle

View the commands for a useful bug report

Four commands. Run them in the repository where the problem happened, and paste what they print rather than summarising it.

```
kin --version
```
The build, its commit and its date. Every answer below depends on which one you are on.
```
kin doctor
```
The install, the daemon, the repository, the graph, the projection, the shell hook and every detected client, each row passing or naming its own fix.
```
kin graph status
```
Entity and relation counts, embedding coverage, parse coverage and when the graph last admitted a change. This is what separates a wrong answer from a stale one.
```
kin status
```
What the repository holds now, whether the working copy is ahead of its base change, and the store size.

A report template

Open the report template

Copy this into the issue and fill it in. The two lines that matter most are what you ran and what it printed, in that order.

What I ran:
  <the exact command>

What I expected:
  <one sentence>

What I got:
  <paste the output, not a description of it>

kin --version:
  <paste>

kin doctor summary line:
  <paste, for example: Summary: 27 passed, 1 need attention, 6 not applicable.>

kin graph status, the coverage lines:
  <paste>

Repository:
  <language, rough size, public or private, and whether it was admitted from Git>

What not to paste

Source code you cannot share. Entity names, file paths and signatures are usually enough, and a small repository that reproduces the problem is better than a large one you have to redact.
Anything under .kin/ wholesale. It holds your repository content. Paste the lines a command printed instead.
Tokens and credentials. kin doctor reports whether a KinLab credential exists, never what it is, and no diagnostic here asks for one.

Next action

Check the message against the list first.

Most of what Kin prints when something looks wrong is a state with a known meaning and a known next step. The troubleshooting page carries them by symptom, with the exact message.

Troubleshooting Kin