Errors And Config Reference

Jidoka funnels every runtime-facing error through Jidoka.Error (a Splode front end) and reads every default through Jidoka.Config. This reference guide documents the error classes, the canonical helpers, and the full defaults table. Use it when wiring telemetry, building app-facing error formatters, or tuning application config.

When To Use This

• Use this guide when you need to know the exact shape and category of a Jidoka error in logs, telemetry, or HTTP responses.
• Use this guide when you are configuring Jidoka defaults under :jidoka in your application config.
• Do not use this guide as a general onboarding doc; see Getting Started.

Prerequisites

• You can compile and run the :jidoka test suite.
• You have basic familiarity with the Splode error library.

Quick Example

Normalizing an arbitrary failure and turning it into wire data is two calls.

case Jidoka.turn(MyApp.TimeAgent, "Hello") do
  {:ok, result} ->
    result

  {:error, reason} ->
    error = Jidoka.normalize_error(reason, phase: :turn)
    Jidoka.format_error(error)
    #=> "Jidoka execution failed."

    Jidoka.error_to_map(error)
    #=> %{category: :execution, message: "Jidoka execution failed.", phase: :turn, details: %{...}}
end

The same helpers are exported as Jidoka.Error.normalize/2, Jidoka.Error.format/1, and Jidoka.Error.to_map/1 for direct use inside the package.

Concepts

╭──────────────╮     ╭─────────────────╮     ╭────────────────╮
│ raw reason   │────▶│ Jidoka.Error    │────▶│ Splode error   │
│ (atom, map,  │     │ .normalize/2    │     │ class struct   │
│  exception)  │     ╰─────────────────╯     ╰────────┬───────╯
╰──────────────╯                                      │
                                                      ▼
                                            ╭──────────────────╮
                                            │ Error.format/1   │
                                            │ Error.to_map/1   │
                                            ╰──────────────────╯

Splode error classes are buckets that group together specific error structs. Every public Jidoka API returns either an :ok tuple or one of the four classes.

Fields

Error Classes

Each class is a Splode error class with an errors: list of one or more concrete error structs (ValidationError, ConfigError, ExecutionError, or Internal.UnknownError).

Error Structs

Jidoka.Error.validation_error/2, config_error/2, and execution_error/2 are the canonical constructors. They take a message and either a keyword list or map of details; the :details map is sanitized before any rendering.

Public Helpers

The four most important error helpers, exported from both Jidoka.Error and the top-level Jidoka facade:

The format/1 and to_map/1 helpers automatically redact secret-like fields (api_key, authorization, password, secret, token) and omit high-cardinality fields (messages, prompt, request_body, etc.).

Jidoka.Config Defaults

Jidoka.Config reads every default through Application.get_env(:jidoka, key, fallback) and validates the value before returning.

Example application configuration:

# config/config.exs
import Config

config :jidoka,
  default_model: "anthropic:claude-3-5-sonnet-latest",
  default_generation: %{params: %{temperature: 0.2, max_tokens: 1_024}},
  default_max_model_turns: 6,
  default_turn_timeout_ms: 45_000

Two additional Jidoka.Config helpers are worth knowing:

Common Patterns

• Always normalize before logging. Raw atoms or tuples lose context; Jidoka.normalize_error/2 adds a category, message, and phase.
• Use error_to_map/1 at the wire boundary. It is JSON-safe and applies secret redaction automatically.
• Set defaults in config, not in agents. spec overrides win, but :jidoka defaults are what unify behavior across modules.
• Treat :invalid as a 4xx and :execution as a 5xx. Mapping Jidoka.Error.category/1 directly to HTTP status codes works well in practice.

Testing

Error tests are most useful when they assert on both the category and the relevant detail.

test "missing input becomes a validation error" do
  error = Jidoka.normalize_error(:missing_input)

  assert Jidoka.Error.category(error) == :validation
  assert %{category: :validation, message: message} = Jidoka.error_to_map(error)
  assert message =~ "input is required"
end

test "config defaults round-trip" do
  Application.put_env(:jidoka, :default_max_model_turns, 12)
  assert Jidoka.Config.default_max_model_turns() == 12
after
  Application.delete_env(:jidoka, :default_max_model_turns)
end

Troubleshooting

Reference

• Jidoka.Error - Splode entry point and helpers.
• Jidoka.Error.Invalid - validation error class.
• Jidoka.Error.Execution - execution error class.
• Jidoka.Error.Config - configuration error class.
• Jidoka.Error.Internal - internal error class (and Internal.UnknownError).
• Jidoka.Error.ValidationError, Jidoka.Error.ConfigError, Jidoka.Error.ExecutionError.
• Jidoka.Config - default_model/0, default_generation/0, default_max_model_turns/0, default_turn_timeout_ms/0, normalize_model_spec/2, model_ref/1.

Related Guides

• Getting Started - first encounter with defaults.
• Agent Spec Contract - where Spec consumes Jidoka.Config defaults.
• Turn And Effect Contracts - the runtime phases that produce execution errors.
• Runtime And Harness - where harness-side errors originate.