ZIO Introduction — Functional Effects for Scala

An effect is a value, not a running computation

The single idea everything else in ZIO depends on is that ZIO is a description of a program, not the program running. Constructing a ZIO value performs no I/O, opens no socket, prints nothing. It builds an immutable data structure -- a tree of nodes saying "run this, then flat-map into that, and if it fails do this instead" -- which sits inert on the heap until a runtime walks it. Nothing in your codebase executes an effect except the one place at the edge that hands the value to the runtime.

import zio._

// Describing. Nothing is printed by these three lines.
val greet: Task[Unit]  = Console.printLine("hello")
val twice: Task[Unit]  = greet *> greet
val thrice: Task[Unit] = greet.repeatN(2)

That indirection is what buys every guarantee the library advertises: because the runtime -- not your code -- decides when a node executes, it can interleave thousands of effects onto a handful of threads, deliver interruption at safe points, run finalizers on every exit path, and retry a subtree without you writing a loop.

The contrast with Scala's Future is the mistake most newcomers arrive with. A Future starts running the moment it is constructed, so referencing it twice does not run it twice; a ZIO value is inert, so referencing it twice really does describe doing the work twice.

val f = Future(charge(card))     // already running, right now
val g = f.zip(f)                 // ONE charge, its result used twice

val z = ZIO.attempt(charge(card)) // nothing has happened
val y = z.zip(z)                 // describes TWO charges, run later

That is ordinary referential transparency applied to side effects, and it is why ZIO code can be refactored aggressively: an effect can be pulled into a val, stored in a Map, or handed to a function that decides whether to run it once, retry it, or race it, without changing what the program means.

ZIO[R, E, A] — reading the three channels

ZIO[R, E, A] has three type parameters, and reading them fluently is most of the on-ramp. The mnemonic that works: given an R, this effect will either fail with an E or succeed with an A. Functionally it behaves like R => Either[E, A] wrapped in the ability to perform effects, be interrupted, and manage resources. The variance is ZIO[-R, +E, +A]: contravariant in what it needs, covariant in how it fails and what it returns, which is what lets effects with different requirements and error types compose without casts.

Unsatisfied requirements accumulate in R as you compose and the program does not compile until every one is provided; E holds the failures a caller is expected to consider, which is often a sealed domain type rather than a Throwable. Two of the three are frequently "nothing", and ZIO ships aliases for those cases. You will see them far more often than the full three-parameter form, so learning the table pays for itself immediately.

Any in the R position means "no requirement left" -- any environment will do, including an empty one. Nothing in the E position is stronger than it looks: because Nothing is uninhabited, a UIO is a compiler-checked promise that this effect has no failure a caller could handle. Signatures therefore carry real information, and the shape of a function's type tells you what it can do to you before you read its body.

Building effects: succeed, attempt, and the impure boundary

Effects come from three places: pure values you lift, impure code you wrap, and callbacks you adapt. The constructor you choose decides where the failure ends up, and choosing wrongly is the most common early mistake.

val pure:    UIO[Int]           = ZIO.succeed(42)
val boom:    IO[String, Nothing] = ZIO.fail("not found")
val risky:   Task[String]       = ZIO.attempt(Source.fromFile("f.txt").mkString)
val jdbc:    Task[ResultSet]    = ZIO.attemptBlocking(stmt.executeQuery(sql))
val adapted: Task[Value]        = ZIO.async[Any, Throwable, Value] { cb =>
  client.onResult(v => cb(ZIO.succeed(v)), e => cb(ZIO.fail(e)))
}

ZIO.succeed takes its argument by name but promises it cannot fail, so it is for code you know is total. ZIO.attempt is the honest wrapper for anything that can throw: it catches the non-fatal Throwable and puts it in the E channel, which is why its result is a Task. Wrapping throwing code in succeed does not make it safe -- the exception becomes a defect instead of a failure, bypassing the error channel entirely.

ZIO.attemptBlocking exists because ZIO multiplexes many effects onto few threads. A JDBC call, a legacy file read, or anything that parks an OS thread must be shifted onto the dedicated blocking pool, or it starves the core pool that every other effect is sharing; the runtime article covers the executors and why this one call matters so much under load. ZIO.async is the adapter for callback APIs: you get a callback that completes the effect exactly once, which is how ZIO wraps Netty, JDBC drivers with async modes, or any listener-based client. For interop with code that already returns a Future, ZIO.fromFuture takes the execution context from the runtime for you.

Composing effects with flatMap and for-comprehensions

Effects compose with the same combinators as any other Scala data structure, which is why for-comprehensions are the dominant idiom. A for block over ZIO is just nested flatMap: each <- means "run this effect, bind its success value, and continue". It reads like imperative code and is nothing of the sort -- the whole block is one value that has not run.

val program: ZIO[Any, Throwable, Unit] =
  for {
    _     <- Console.printLine("whose profile?")
    name  <- Console.readLine
    user  <- fetchUser(name)
    posts <- ZIO.foreach(user.postIds)(fetchPost)
    _     <- Console.printLine(s"${user.name}: ${posts.size} posts")
  } yield ()

Notice how the type parameters combined. Each step contributed its own requirements and errors, and the compiler took the union of the Rs and the least upper bound of the Es. You never write that unification; it is a consequence of the variance. If fetchUser had needed a UserRepo, the whole program would have had type ZIO[UserRepo, Throwable, Unit] and would not run until something supplied one.

Around flatMap sits a large combinator vocabulary -- foreach and collectAll for collections, tap for logging, when for conditional execution -- and the naming is regular enough to guess at: a Par suffix means concurrency, a ZIO suffix means the function you pass is itself effectful, and a Discard suffix means the results are thrown away. When the sequence is unbounded or too large to hold in memory, the same compositional style continues in ZStream, which replaces the collection with a pull-based, backpressured flow of chunks.

Typed errors, and the defects underneath them

The error channel is the feature that changes how you design an API. In ordinary Scala, a method returning User may also throw, and nothing in the signature says which exceptions or whether any are expected; you find out from a stack trace in production. In ZIO the expected failures are the E parameter, so the compiler knows them, and a caller who does not handle them carries them onward in its own type.

sealed trait UserError
case class  NotFound(id: Long) extends UserError
case object Unauthorized       extends UserError

def load(id: Long): IO[UserError, User] = ???

val recovered: UIO[User] =
  load(7).catchAll {
    case NotFound(_)  => ZIO.succeed(User.anonymous)
    case Unauthorized => ZIO.succeed(User.guest)
  }

Because catchAll here handled every case, the result type became UIO[User] -- Nothing in the error position, a proof that this effect can no longer fail. That is the pattern worth internalising: recovering from errors is a type-level operation, and the neighbouring combinators (catchSome, mapError, either, foldZIO) all differ in exactly what they leave behind in E.

ZIO.attempt(parse(s)).mapError(e => BadInput(e.getMessage))  // Throwable to domain error
readConfig.orDie                                            // Throwable failure becomes a defect
load(7).orDieWith(e => new RuntimeException(e.toString))    // promote any E to a defect

The second half of the story is the distinction between failures and defects. A failure is an expected error in E: the user was not found, the payment was declined. A defect is a bug -- a null dereference, an assertion that should have held -- and it deliberately does not appear in the type, because no caller can sensibly handle every bug; defects travel separately and surface at the top of the fiber. orDie is how you say "if this fails, the program is broken", converting a failure into a defect on purpose.

Both live inside a richer structure called Cause, which also records interruption and the several failures that a parallel effect can produce at once. You mostly do not touch it, but when you need the full picture -- logging a failure with its defects and suppressed causes intact -- it is there, and the runtime article develops how Cause, interruption, and fiber failures fit together.

Running a program: ZIOAppDefault and the runtime

Since effects do not run themselves, something has to. The normal answer is ZIOAppDefault: extend it, define run, and you have a main class. It builds the default runtime, supplies the built-in services, runs your effect on a root fiber, translates the outcome into an exit code, and installs a graceful shutdown path so finalizers get a chance to run on SIGTERM.

import zio._

object Main extends ZIOAppDefault {

  val program: ZIO[Any, Throwable, Unit] =
    for {
      _ <- Console.printLine("starting")
      _ <- ZIO.sleep(1.second)
      _ <- Console.printLine("done")
    } yield ()

  def run = program
}

Two details in that snippet are load-bearing. ZIO.sleep does not block a thread -- the fiber suspends and its carrier thread goes off to run other work, which is why sleeping a million fibers costs almost nothing. And run may require an environment; whatever it still needs must be provided before the app compiles, which is the subject of the next section.

Console, Clock, Random and System are built into the runtime, so effects that use them have no leftover requirement. That is a deliberate choice: the services almost every program needs are pre-provided, and only your own services show up in R.

When ZIO is embedded rather than in charge -- a call inside a Spring controller or an Akka actor -- there is an explicit unsafe escape hatch on the runtime that runs an effect and returns its result to the calling thread; it is deliberately awkward to write, because every use is a boundary where the guarantees stop, and the runtime article covers what it does.

The environment R, and how you satisfy it

R is the parameter that surprises people, so it helps to see it as ordinary dependency injection with the wiring moved into the type system. An effect that needs a service asks for it, and the requirement shows up in its type until somebody satisfies it.

trait UserRepo {
  def find(id: Long): IO[NotFound, User]
}

def findUser(id: Long): ZIO[UserRepo, NotFound, User] =
  ZIO.serviceWithZIO[UserRepo](_.find(id))

val live: ZLayer[DataSource, Nothing, UserRepo] =
  ZLayer { ZIO.service[DataSource].map(ds => PostgresUserRepo(ds)) }

object Main extends ZIOAppDefault {
  def run = findUser(7).provide(live, DataSource.layer)
}

ZIO.service[A] retrieves a service from the environment; ZIO.serviceWithZIO retrieves it and immediately calls an effectful method on it. The requirement propagates outward through every caller automatically -- you never thread a parameter by hand -- and provide is the moment you discharge it. Supply layers that do not cover everything and the code does not compile, with an error naming the missing service.

A ZLayer[RIn, E, ROut] is a recipe for building services: it may itself require other services, may fail while constructing (a bad config, an unreachable database), and produces the service it describes. Because layers are values, swapping the real repository for an in-memory one in a test is a one-word change at the provide call rather than a mocking framework.

Everything past that first acquaintance -- horizontal and vertical composition, why each layer is memoized so a connection pool is built exactly once no matter how many consumers need it, and how scoped layers release resources in reverse acquisition order at shutdown -- is developed in the ZLayer architecture article, which is where to go the moment your dependency graph outgrows a single provide.

Concurrency: fork, race, and interruption that cleans up

Concurrency in ZIO is not threads. fork takes an effect and starts it on a fiber: a heap-allocated, cheap, interruptible unit of execution that the runtime multiplexes onto a small thread pool. Forking is as cheap as allocating an object, which is why the natural style is to fork freely rather than to husband a scarce pool.

for {
  fiber <- longRunning.fork      // starts concurrently, returns a handle
  other <- somethingElse         // runs while the fiber is in flight
  value <- fiber.join            // waits for the result
} yield (value, other)

val fastest = primary.race(replica)        // first to finish wins
val both    = left.zipPar(right)           // both in parallel, fail fast
val many    = ZIO.foreachPar(ids)(fetch)   // bounded fan-out

The behaviour that makes this safe rather than merely convenient is interruption. When race has a winner, the loser is interrupted -- and interruption in ZIO is not a thread kill: the losing fiber is stopped at a safe point, its registered finalizers run, and only then does it report that it was interrupted. The same applies to timeout, to a failing sibling in zipPar, and to shutdown. Abandoned work does not leak the connection it was holding.

The second guarantee is structure. A fiber forked inside a scope belongs to that scope, so when the parent finishes or is interrupted its children are interrupted too. You cannot accidentally leave a background fiber running after the request that spawned it is gone. The fibers article traces exactly how forking, suspension, interruption and supervision play out in a real request, and is the next stop once you start forking on purpose.

For state shared between fibers, reach for Ref, Promise, Queue and Hub before anything with a lock; when one update must span several of those cells atomically, that is what ZIO's software transactional memory is for, and it composes where locks do not.

Resources, timeouts, and retry schedules

Resource safety is the third pillar, and it is what most convinces teams to adopt the library. ZIO.acquireReleaseWith pairs an acquisition with a release that the runtime guarantees will run -- on success, on failure, and on interruption alike. There is no exit path that skips it.

val query: Task[List[Row]] =
  ZIO.acquireReleaseWith(ZIO.attempt(pool.getConnection))(c => ZIO.succeed(c.close()))(
    conn => ZIO.attemptBlocking(runQuery(conn))
  )

The release function is deliberately not allowed to fail -- it returns an effect that cannot error -- because a finalizer that might itself fail makes the guarantee meaningless. When you have several resources, ZIO.scoped and ZIO.acquireRelease let each one register its finalizer against a shared Scope that closes them in reverse order of acquisition, which is the same mechanism layers use at application scale.

Retries and timeouts are built from the same descriptive style. A Schedule is a value describing a recurrence policy -- exponential backoff, a fixed number of attempts, jitter, a maximum elapsed time -- that you compose and hand to retry or repeat. Because policies are values, the backoff strategy for a flaky third party can be defined once, named, tested, and reused everywhere.

val resilient =
  callService
    .timeoutFail(ServiceTimeout)(2.seconds)
    .retry(Schedule.exponential(100.millis) && Schedule.recurs(3))
    .catchAll(_ => ZIO.succeed(cachedFallback))

Each combinator there returned a new description; nothing ran. The equivalent against blocking code is a thread pool, a scheduled executor, a cancellation flag, and a great deal of care about which of them owns the connection.

Where each concern is developed next

This article is deliberately one level deep on every topic. Here is where each concern is developed properly, in roughly the order a new team hits them.

Start with the ZIO runtime once you want to know what is actually happening underneath: how an effect tree is interpreted, how the work-stealing executor schedules fibers, why one unwrapped blocking call can stall a service, and how Cause, interruption and graceful shutdown fit together. It is the article that turns the guarantees from claims into mechanics.

Then fibers and structured concurrency, as soon as you fork anything on purpose: fork and join, suspension and resumption, interruption at yield points with finalizers guaranteed, supervision that ties a child's lifetime to its parent, and the operational failure modes -- fiber leaks, unbounded forking, blocking on the wrong pool.

Then ZLayer, the moment your R has more than two entries: composing layers horizontally and vertically, the compile-time completeness check, memoization so a shared pool is built exactly once, and scoped teardown in reverse dependency order.

For data pipelines, ZStream: pull-based, chunked streaming with automatic backpressure, resource-safe sources, and the pipeline and sink vocabulary that turns a Kafka-to-database ingestion into one composed value with flat memory usage. For shared state under contention, ZIO STM: transactional references, optimistic commit with automatic re-run, and the composability that plain locks cannot give you.

Two neighbouring things are worth knowing about. Cats Effect is the other major Scala effect system, with the same core idea and a different set of trade-offs -- notably no environment parameter, with dependencies passed as constructor arguments instead. Tagless final is the style that abstracts over which effect type you use at all, and it is the usual alternative when a library must not force ZIO on its callers. On the language side, ZIO 2 leans on features covered in Scala 3 -- given/using, opaque types, union types -- and reading that first makes several ZIO signatures stop looking cryptic.