Troubleshooting

Symptoms: kast health returns an error or hangs.

1. Verify the workspace root exists and contains Kotlin sources:

   kast health --workspace-root=/path/to/project
   

2. Check that Java 21 or newer is available:

   java -version
   

3. Look for a stale socket file. If the daemon crashed without cleanup, the socket may still exist:

   ls /tmp/kast-*.sock
   

   Remove any stale sockets and retry.

The daemon indexes the entire workspace on first start. Large projects with many modules may take 30–60 seconds.

• Run kast workspace status to monitor indexing progress.
• Wait for state: READY before running analysis queries.
• If indexing never completes, check that the Gradle wrapper in the project is functional (./gradlew tasks should succeed).
• Pass --accept-indexing=true to workspace ensure if you can tolerate partial results while indexing finishes.

Open a new shell session so the updated PATH takes effect. If that doesn't help:

• Check whether the install root is on your PATH: echo $PATH | tr ':' '\n' | grep kast
• Set KAST_CLI_PATH to point directly at the binary: export KAST_CLI_PATH=/absolute/path/to/kast

Symptoms: kast resolve returns an empty result or a NOT_FOUND error.

• Confirm the file path is absolute and within the workspace root.
• Confirm the offset points at an actual symbol (identifiers, not whitespace or comments).
• Verify the daemon finished indexing (kast workspace status shows state: READY).
• If the file was recently created, run kast workspace refresh to update the workspace index.

Kast scopes all analysis to the workspace root. References in files outside the workspace, in generated code, or in binary dependencies are not included.

Check searchScope.exhaustive in the response:

• true — every candidate file was searched. The list is complete.
• false — the search was bounded. Compare candidateFileCount and searchedFileCount to see the gap.

See Behavioral model for details on workspace scoping and visibility rules.

Call hierarchy results are bounded by depth, fan-out, total edges, and timeout. Check the stats field in the response to see whether limits were hit.

Adjust these parameters in the request:

See Behavioral model for the full truncation model.

Both standalone and IntelliJ backends support rename. Run kast capabilities to verify.

If the rename target is in a generated file or a read-only location, the operation may fail with a descriptive error.

This means a file changed between when you planned the edit and when you applied it. The SHA-256 hash no longer matches.

1. Re-run the rename command to get a fresh plan with updated hashes.
2. Review the new plan.
3. Apply it immediately before any other changes land.

When using stdio transport (for example, from an LLM agent):

• Verify the daemon process is running and attached to stdin/stdout.
• Confirm no other process is competing for the same stdio streams.
• Verify JSON-RPC messages are line-delimited (one JSON object per line).

If you change analysis-api model classes, drift tests may fail. Run all three generation commands:

./gradlew \
  :analysis-server:generateDocExamples \
  :analysis-api:generateDocPages \
  :analysis-api:generateOpenApiSpec