Kode Verification Gate Failures: Diagnosis and Fixes

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 <check> 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

kode explain syntax
kode explain imports
kode explain calls
kode explain architecture
kode explain diff_applier

Pass --log-dir <path> if your audit log lives somewhere other than <cwd>/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 below)
Incorrect indentation in Python where dedent was expected but never emitted

How to fix:

Run kode explain syntax — it prints the exact parse error detail including file path, line, and column.
Open the file at that line and look for the unclosed bracket or unexpected token.
If the file looks mangled, the patch likely landed on a stale version. Run kode explain diff_applier as well.
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:

Run kode explain imports — the Details field lists every unrecognized import path.
For Go: check go.mod for the actual module path. If the dependency is legitimate, run go get <package> and commit the updated go.mod before re-running.
For TypeScript/JavaScript: confirm the package is in node_modules. If not, install it first.
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:

Run kode explain calls — it shows the offending call site and, when available, the nearest real symbols from the context graph.
Check the actual API documentation or source for the package.
Re-run your task with the correct function signature quoted in the prompt: “Call json.Marshal(v) which returns ([]byte, error).”
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:

Run kode explain architecture — it shows which import crossed which boundary.
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.
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:

Run kode explain diff_applier — it shows what the patch expected to find in the file vs. what was actually there.
Re-run the task so Kode re-reads the current file state before generating the patch.
Avoid editing files manually while a kode loop is running.
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:

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.

Documentation Index

​Getting Details on a Failure

​Syntax Gate Failures

​Imports Gate Failures

​Calls Gate Failures

​Blast Radius Gate Failures

​Architecture Gate Failures

​Security Gate Failures

​Diff Applier Failures

​Reviewing Recent Failures

Getting Details on a Failure

Syntax Gate Failures

Imports Gate Failures

Calls Gate Failures

Blast Radius Gate Failures

Architecture Gate Failures

Security Gate Failures

Diff Applier Failures

Reviewing Recent Failures