🎯

cats-mtl-typed-errors

🎯Skill

from alexandru/skills

What it does

Enables typed error handling in Scala using Cats MTL Raise/Handle, supporting custom domain errors without EitherT transformers.

📦

Part of

alexandru/skills(8 items)

cats-mtl-typed-errors

Installation

Quick InstallInstall with npx

npx skills add https://github.com/alexandru/skills --skill <skill-name>

📖 Extracted from docs: alexandru/skills

Need more details? View full documentation on GitHub →

3Installs

AddedFeb 4, 2026

View on GitHub Back to Skills

Skill Details

SKILL.md

Scala typed errors with Cats MTL Raise/Handle and allow/rescue. Use for designing custom domain error types without EitherT, while keeping Cats Effect and ecosystem composition. Covers Scala 2/3 syntax and IO-only or F[_] usage.

Overview

# Cats MTL Typed Errors (Scala)

Quick start

Define a domain error type; it may or may not extend Throwable depending on context.
Use Cats MTL Raise[F, E] in functions that can raise errors.
Use Handle.allow/rescue (Scala 3) or Handle.allowF (Scala 2) to introduce a scoped error capability and handle it like try/catch.
Prefer Cats MTL over IO[Either[E, A]] and avoid EitherT[IO, E, A]; pure functions returning Either[E, A] are fine at API boundaries.
F[_] is optional: you can write IO-specific code or keep F[_] for polymorphism, depending on the project.

Workflow

Model domain errors as sealed ADTs (Scala 2) or enums (Scala 3)
For effectful code that can raise errors, require Raise[F, E] (and Monad[F] or Applicative[F]).
Raise errors with .raise and return successful values with pure.
At a boundary, use Handle.allow (Scala 3) or Handle.allowF (Scala 2) to create a scope where raises are valid.
Close the scope with .rescue to handle each error case explicitly.
Keep Cats Effect resource and concurrency semantics intact by staying in the monofunctor error channel.

Patterns to apply

Typed errors in signatures: treat the error type parameter E as the checked-exception channel in the function signature.
Scoped error capabilities: require Raise[F, E] in functions that can fail; use Handle[F, E] when you also need to recover.
Scala 3 ergonomics: prefer using and context functions with allow; type inference is significantly better.
Scala 2 compatibility: use allowF and explicit implicit parameters; expect more braces and explicit types.
Interop with pure code: use pure Either[E, A] for parsing/validation and lift into F where needed.
Avoid transformer stacks: do not reach for EitherT just to get a typed error channel; Cats MTL provides the capability without the stack.
Avoid sealed-on-sealed inheritance: model error hierarchies with composition (wrapper case classes), not sealed inheritance chains.

References

Load references/custom-error-types.md for detailed guidance, Scala 2/3 syntax, and rationale from the Typelevel article.

More from this repository7

🎯

arrow-resource🎯Skill

Manages safe resource lifecycle in Kotlin using Arrow's `Resource`, enabling deterministic acquisition, release, and composition of resources like files, streams, and connections.

🎯

cats-effect-resource🎯Skill

Manages safe resource lifecycle in Scala using Cats Effect `Resource`, enabling composable and cancellation-safe resource handling.

🎯

compose-state-hoisting🎯Skill

Guides Kotlin Compose developers in hoisting state effectively, ensuring unidirectional data flow and clear state ownership across UI components.

🎯

cats-effect-io🎯Skill

Manages Scala side effects and concurrency using Cats Effect IO, providing safe, pure functional programming with resource handling and structured concurrency.

🎯

arrow-typed-errors🎯Skill

Enables robust, type-safe error handling in Kotlin using Arrow's Raise DSL and wrapper types for composable, expressive error management.

🎯

akka-streams🎯Skill

Enables reactive dataflow programming in Scala using Akka and Pekko Streams, with emphasis on testable components and selective stream usage.

🎯

kotlin-java-library🎯Skill

Converts and migrates Kotlin and Java code between libraries, supporting seamless interoperability and code transformation.