> ## Documentation Index > Fetch the complete documentation index at: https://docs.trykode.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Kode Verification Gate Failures: Diagnosis and Fixes > Diagnose Kode verification gate failures for syntax, imports, calls, blast radius, architecture, and security. Covers causes and fixes for each gate. Gate failures are not errors to ignore — they are the mechanism that keeps bad code off your filesystem. Every time Kode generates a patch, the verification gate runs a sequence of checks against the modified files in memory, before anything is written to disk. When a check fails, Kode halts immediately and reports which gate tripped and why. Your job is to read that signal, understand the root cause, and decide whether to refine your prompt, adjust configuration, or reject the change entirely. ## Getting Details on a Failure Run `kode explain ` for a full Markdown breakdown of any gate type, including a description, common causes, suggested fixes, and up to five recent examples pulled directly from your audit log at `logs/kode.log`. The five check names you can pass to `kode explain` are: | Check name | Gate it describes | | -------------- | ---------------------------------------- | | `syntax` | Parse errors and malformed code | | `imports` | Unresolvable or forbidden imports | | `calls` | Hallucinated or incorrect function calls | | `architecture` | Module boundary violations | | `diff_applier` | Patches that cannot be applied cleanly | ```bash theme={null} kode explain syntax kode explain imports kode explain calls kode explain architecture kode explain diff_applier ``` Pass `--log-dir ` if your audit log lives somewhere other than `/logs`. *** ## Syntax Gate Failures The Syntax Gate runs first. A parse error is a hard block — Kode will not continue to any other check if it cannot confirm the file is syntactically valid. **What it catches:** Parse errors, malformed code, and invalid syntax for the target language. Kode detects the language from the file extension and applies a language-specific check. **Supported languages:** | Language | Check method | | ---------- | ----------------------------------------------------------- | | Go | Full AST parse via `go/parser` | | TypeScript | Bracket/paren/brace balance + string/comment awareness | | JavaScript | Bracket/paren/brace balance + template literal awareness | | Python | Bracket balance + triple-quoted string and comment handling | | Rust | Bracket/paren/brace balance | Files in other languages pass through the Syntax Gate without blocking. **Common causes:** * The LLM generated incomplete code — a missing closing brace `}`, an unclosed string literal, or a half-written function body * Language mismatch: the model used TypeScript type annotations (e.g., `const x: string`) inside a plain `.js` file * A patch was applied on top of an already-modified file, leaving the file in a corrupt state (see [Diff Applier failures](#diff-applier-failures) below) * Incorrect indentation in Python where dedent was expected but never emitted **How to fix:** 1. Run `kode explain syntax` — it prints the exact parse error detail including file path, line, and column. 2. Open the file at that line and look for the unclosed bracket or unexpected token. 3. If the file looks mangled, the patch likely landed on a stale version. Run `kode explain diff_applier` as well. 4. Refine your prompt to be explicit about the target language: *"Add a Go function…"* instead of leaving it ambiguous. For Go files, Kode uses the full `go/parser` which reports the exact line and column in the `Details` field. For other languages, it reports the character position of the first mismatched bracket. *** ## Imports Gate Failures After the file passes syntax, the Imports Gate checks every `import`, `require`, or `from … import` statement in the changed file. An import that cannot be resolved to your project's dependency graph is a hard block in Go. TypeScript, JavaScript, and Python produce warnings rather than hard blocks when imports are ambiguous. **What it catches:** Import or require statements that reference packages not present in your project's dependency manifest (`go.mod`, `node_modules`, or the Python environment). **Common causes:** * The LLM hallucinated a package name — e.g., `import "github.com/nonexistent/pkg"` for a library that does not exist * The package exists on the internet but isn't listed in `go.mod` or installed in `node_modules` * The import path is correct in concept but wrong in detail: a wrong version suffix, a renamed module, or a misspelled path segment * An internal package is imported from outside its allowed scope (e.g., importing `internal/auth` from a different module) **How to fix:** 1. Run `kode explain imports` — the `Details` field lists every unrecognized import path. 2. For Go: check `go.mod` for the actual module path. If the dependency is legitimate, run `go get ` and commit the updated `go.mod` before re-running. 3. For TypeScript/JavaScript: confirm the package is in `node_modules`. If not, install it first. 4. If the import is simply wrong (hallucinated name), refine your prompt by quoting the exact package path you want: *"Use `github.com/google/uuid` for UUID generation."* The Go import checker reads `go.mod` at startup. If you add a new dependency after Kode has started, restart the session or the import validator will not see the new entry. *** ## Calls Gate Failures The Calls Gate checks whether function and method calls in the changed file reference symbols that actually exist in your codebase. Calls to hallucinated methods on real types are a hard block. **What it catches:** Function or method calls to symbols that are not defined in your project's dependency graph — for example, calling `.Serialize()` on a type that only has `.Marshal()`, or passing the wrong number of arguments to a known function. **Common causes:** * The LLM hallucinated a method name on a real type (the package is correct, but the method never existed) * Calling a function defined on an interface that the concrete type doesn't implement * Using an unexported function from another package * Wrong number of arguments, or mishandling return values (e.g., ignoring an `error` return) **How to fix:** 1. Run `kode explain calls` — it shows the offending call site and, when available, the nearest real symbols from the context graph. 2. Check the actual API documentation or source for the package. 3. Re-run your task with the correct function signature quoted in the prompt: *"Call `json.Marshal(v)` which returns `([]byte, error)`."* 4. Provide more context — include the relevant type or interface definition in the prompt so the model has the real signature. *** ## Blast Radius Gate Failures The Blast Radius Gate prevents a single patch from silently cascading changes across your entire codebase. It uses the context graph (built from your module's import relationships) to count how many downstream files would be affected if the modified file's signature changes. **What it catches:** Patches that would modify a file depended upon by more downstream files than your configured threshold. **Configuration:** The threshold is set via `engine.max_blast_radius` in `.kode/kode.json` (default: `3`). The gate only activates when blast radius checking is configured; without it, the gate is a no-op. **Common causes:** * Changing a widely-used interface or a shared type signature * Modifying a core utility (e.g., a logger, a config struct) that is imported by many packages * Adding a required parameter to a function that is called throughout the codebase **How to fix:** * **Increase the threshold** for a deliberate large refactor: set `engine.max_blast_radius` to a higher value in `.kode/kode.json`. * **Break the task into smaller scoped changes**: modify only the internal implementation without touching the exported signature, then update callers in separate tasks. * **Scope your prompt more tightly**: specify exactly which file and function to change without touching the public API. Raising `max_blast_radius` to a very high value (or disabling it entirely) reduces a core safety guarantee. Prefer smaller, incremental changes over one large refactor. If you do raise it, review the full diff carefully before accepting. *** ## Architecture Gate Failures The Architecture Gate enforces declared module boundaries — for example, preventing a `service/payments` package from importing directly from `service/inventory` when your architecture rules forbid inter-service imports. **What it catches:** Imports that cross a boundary declared in your architecture rules — circular dependencies, layer violations (e.g., a `handler` importing from a `repository` directly), or internal packages leaked to external consumers. **Activation:** This gate only runs when `--block-architecture` is passed to `kode verify`, or when architecture rules are declared in your Kode configuration. Without rules, the gate is a no-op. **Common causes:** * Code in one layer importing from a forbidden layer (e.g., presentation layer importing infrastructure directly) * A circular dependency introduced between two packages * An `internal/` package being imported from outside its allowed scope **How to fix:** 1. Run `kode explain architecture` — it shows which import crossed which boundary. 2. Restructure the code to respect the layer boundary: move the logic to an appropriate package, or define an interface in the allowed layer and inject the implementation. 3. If the architecture rule is intentionally outdated, update the rules in `.kode/kode.json` to reflect the new design. Without `--block-architecture`, architecture violations are downgraded to warnings (`WARN` status) and do not block the write. They still appear in `kode stats` and the audit log. *** ## Security Gate Failures The Security Gate scans modified files for high-severity vulnerabilities before they reach disk. It requires the Sicario SAST binary to be installed. **What it catches:** SQL injection patterns, cross-site scripting (XSS) vulnerabilities, hardcoded secrets and API keys, and other patterns Sicario classifies as high or critical severity. **Activation:** Requires `kode install sicario`, which downloads and installs the Sicario binary to `.kode/`. Without it, the security check produces a warning ("Sicario not found") and the write proceeds — it does not hard-block. **Severity behavior:** | Severity | Effect | | ---------------- | ------------------------------------------- | | Critical or High | Hard block — write is rejected | | Medium or Low | Warning — write proceeds, finding is logged | | Sicario absent | Warning — write proceeds, finding logged | **How to fix:** * Review the security report printed to stderr when a finding blocks. * `kode explain` does not yet provide built-in Sicario guidance — inspect the raw finding output directly. * Address the underlying issue in your prompt: *"Do not use string interpolation in SQL queries — use parameterized queries."* * For false positives, consult the Sicario documentation to add suppressions. *** ## Diff Applier Failures The Diff Applier is the first step in the gate sequence, not technically a "gate check" in isolation, but reported the same way. It runs before any other check. **What it catches:** Patches that cannot be cleanly applied to the current file contents. This is not a code quality issue — it means the patch Kode generated was based on a version of the file that no longer matches what's on disk. **Common causes:** * The file was modified between when Kode read it for context and when it attempted to apply the patch * The LLM generated a patch for the wrong version of the file (stale context) * Concurrent edits from another tool (your editor, a formatter, another process) changed the file in the meantime * The diff format was corrupted or used incorrect context lines **How to fix:** 1. Run `kode explain diff_applier` — it shows what the patch expected to find in the file vs. what was actually there. 2. Re-run the task so Kode re-reads the current file state before generating the patch. 3. Avoid editing files manually while a `kode loop` is running. 4. If your formatter runs automatically on save, configure it to run before Kode starts rather than concurrently. *** ## Reviewing Recent Failures Use `kode stats` to get an at-a-glance summary of your project's verification history: ```bash theme={null} kode stats kode stats --top 20 # Show top 20 most-failing files kode stats --days 30 # Extend daily trend to 30 days kode stats --log-dir ./logs ``` `kode stats` shows: * Total verifications with pass/fail counts and rates * Failure breakdown by gate type (so you can see which gate trips most often) * Most frequently failing files * Models used and their share of verifications * A daily pass-rate trend chart for the last 14 days (configurable with `--days`) * A sparkline of the last 20 verdicts as `✓`/`✗` symbols All verification results are written to `logs/kode.log` as JSONL in your project directory. Each line is a JSON object with `timestamp`, `status`, `files`, `failures`, `rounds_used`, `duration_ms`, and `model`. You can query this file directly with `jq` for custom analysis.