Debug and Handle Errors in Migrated Clojure Code

Debugging Clojure in a Java system is less mysterious when you remember that both languages run on the JVM. Stack traces, exceptions, logging, profilers, and thread dumps still matter. What changes is how much of the code can be inspected as data and re-run at the REPL.

The best migration debugging strategy is to make the Clojure slice small, pure, and observable before it owns production effects.

Read The Failure Boundary

When Clojure fails inside Java, first locate the boundary.

This boundary-first approach prevents random debugging. It tells you whether the bug is in orchestration, conversion, decision logic, or effects.

Prefer Reproducible Data

Instead of stepping through a large service graph, capture the input map that reached the Clojure function.

1(def failing-input
2  {:customer {:customer/id "C-42"
3              :customer/credit-limit 1000M}
4   :orders [{:order/id "O-1"
5             :order/outstanding-amount 250M
6             :order/past-due? true}
7            {:order/id "O-2"
8             :order/outstanding-amount nil
9             :order/past-due? false}]})

Now the failure can be reproduced without the controller, repository, transaction, and email service.

1(account-summary (:customer failing-input)
2                 (:orders failing-input))

If this fails, the team can decide whether nil is invalid input, a conversion bug, or a domain case the function should handle.

Use ex-info For Context

Java developers are used to exception classes carrying meaning. In Clojure, ex-info lets you attach structured data to a failure.

1(defn require-money [value path]
2  (if (some? value)
3    value
4    (throw (ex-info "Missing money value"
5                    {:error/type :invalid-input
6                     :error/path path}))))

Java can still catch the exception. Clojure code can inspect the data with ex-data.

1(try
2  (require-money nil [:orders 1 :order/outstanding-amount])
3  (catch clojure.lang.ExceptionInfo ex
4    (ex-data ex)))

Use structured exception data for broken assumptions, not for every expected domain result.

Separate Domain Outcomes From System Failures

Not every unhappy path should be an exception.

Expected business outcomes should usually be values. Broken system conditions should be visible failures.

REPL Debugging In A Migration Slice

Use the REPL to reduce the bug to one expression.

1(->> (:orders failing-input)
2     (map :order/outstanding-amount)
3     (remove nil?)
4     (reduce + 0M))

Then decide whether removing nil is correct. The REPL makes it easy to test a fix; code review still decides whether the fix matches the domain.

Do not leave the bug fix as REPL history. Convert the captured case into a test.

Logging And Observability

Debugging production migrations requires correlation, not print statements scattered everywhere.

Use println locally when it is the fastest way to understand a pure function. Use structured logging and metrics for production behavior.

Practice

1. Capture one failing Java-to-Clojure input as EDN.
2. Reproduce the failure at the REPL without the Java service graph.
3. Decide whether the failure is invalid input, a domain result, or a broken system condition.
4. Add either a value-returning domain test or an ex-info failure test.

Key Takeaways

• Start debugging by locating the failure boundary.
• Captured Clojure data makes production-shaped failures reproducible.
• ex-info is useful when an exception needs structured context.
• Domain outcomes should often be values; broken assumptions should fail visibly.
• Every REPL-discovered bug should become a regression test.

Quiz: Debugging And Error Handling