Skip to Content
Reference@streamsy/core

Errors

Reference for the protocol errors in @streamsy/core. Each error is a tagged class, and you catch it by its tag.

import { OffsetMismatch, StaleEpoch, isProtocolError, type AppendErrorFor } from "@streamsy/core";

The stream operations fail with these errors when the protocol rejects a request. Each error is a Schema.TaggedError, so it is an Error with a _tag that you can yield* in Effect.gen. To handle a specific error, catch it by its tag:

import { Effect } from "effect";
import { Notes } from "./streams.ts";

const write = Effect.flatMap(Notes, (notes) =>
  notes.append({}, [{ id: "n1", text: "hello" }]),
).pipe(Effect.catchTag("StreamClosed", (error) => Effect.succeed(error.offset)));

Each block below shows the _tag and the fields of an error. Every error also has message, name, and stack. The id field is a StreamId, which is a branded string.

Failures of the store, the network, or the codec are faults, such as StorageFault and EncodeFault. They are on the Faults page.

Error classes

StreamNotFound

interface StreamNotFound {
  readonly _tag: "StreamNotFound";
  readonly id: StreamId;
}

An operation fails with StreamNotFound when no stream has the id id.

StreamGone

interface StreamGone {
  readonly _tag: "StreamGone";
  readonly id: StreamId;
}

An operation fails with StreamGone when the stream id existed and was deleted.

StreamClosed

interface StreamClosed {
  readonly _tag: "StreamClosed";
  readonly id: StreamId;
  readonly offset: string;
}

An append fails with StreamClosed when the stream is closed. offset is the tail at which the stream was closed.

OffsetMismatch

interface OffsetMismatch {
  readonly _tag: "OffsetMismatch";
  readonly id: StreamId;
  readonly expected: string;
  readonly actual: string;
}

An append fails with OffsetMismatch when the tail of the stream is not its expectedOffset. expected is the offset that the append sent, and actual is the current tail. The append writes nothing. See Conditional writes.

AppendConflict

interface AppendConflict {
  readonly _tag: "AppendConflict";
  readonly id: StreamId;
}

An append fails with AppendConflict in two cases: its content type differs from the content type of the stream, or its Stream-Seq does not sort after the previous one. message says which case applies.

StreamBusy

interface StreamBusy {
  readonly _tag: "StreamBusy";
  readonly id: StreamId;
}

An append fails with StreamBusy when other writers keep committing to the stream first. The append plans its write again after each lost commit, and it gives up after 64 attempts. The request is safe to send again. Over HTTP, the server answers StreamBusy with a 503.

StaleEpoch

interface StaleEpoch {
  readonly _tag: "StaleEpoch";
  readonly id: StreamId;
  readonly currentEpoch: number;
}

An append fails with StaleEpoch when its producer epoch is lower than the last epoch that the stream accepted for the same producerId. currentEpoch is that last epoch. See Producer.Position.

ProducerGap

interface ProducerGap {
  readonly _tag: "ProducerGap";
  readonly id: StreamId;
  readonly expectedSeq: number;
  readonly receivedSeq: number;
}

An append fails with ProducerGap when its producerSeq skips a number. expectedSeq is the next number that the server accepts, and receivedSeq is the number that the append sent.

InvalidEpochSeq

interface InvalidEpochSeq {
  readonly _tag: "InvalidEpochSeq";
  readonly id: StreamId;
}

The protocol append fails with InvalidEpochSeq when the producer epoch or sequence is not valid, for example a new epoch that does not start at producerSeq 0. The append method of a stream class does not list this error in its type. When a host returns it, the append dies with a defect.

InvalidAppendRequest

interface InvalidAppendRequest {
  readonly _tag: "InvalidAppendRequest";
  readonly id: StreamId;
}

The protocol append fails with InvalidAppendRequest when the request is not valid, for example an append with no items and no close. message says why. The append method of a stream class does not list this error in its type. When a host returns it, the append dies with a defect.

InvalidCreateRequest

interface InvalidCreateRequest {
  readonly _tag: "InvalidCreateRequest";
  readonly id: StreamId;
}

create and fork fail with InvalidCreateRequest when both ttlSeconds and expiresAt are set, including when ttlSeconds is 0. They also fail when DateTime.make cannot parse expiresAt. The local protocol checks these options before storage access. The remote client checks them before sending a request.

A plain create also fails with InvalidCreateRequest when a new JSON stream has invalid initialData. The remote client returns InvalidCreateRequest for a plain create HTTP 400 response without stream-not-supported. message says why. Typed stream create and fork methods surface InvalidCreateRequest as a typed failure.

CreateConflict

interface CreateConflict {
  readonly _tag: "CreateConflict";
  readonly id: StreamId;
  readonly reason?:
    "config-mismatch" | "soft-deleted" | "fork-content-type" | "fork-source-soft-deleted";
}

A create or a fork fails with CreateConflict when its options do not match the stream that already has the id. reason says why, and message describes the conflict. An HTTP response does not carry the reason, so the remote client leaves reason out.

ForkSourceNotFound

interface ForkSourceNotFound {
  readonly _tag: "ForkSourceNotFound";
  readonly id: StreamId;
  readonly source: StreamId;
}

A fork fails with ForkSourceNotFound when its source stream does not exist. id is the stream that the fork would create, and source is the missing source.

InvalidForkRequest

interface InvalidForkRequest {
  readonly _tag: "InvalidForkRequest";
  readonly id: StreamId;
}

A fork fails with InvalidForkRequest when its fork offset is not a valid offset, when the offset is past the tail of the source, or when a new JSON fork has invalid initialData. The remote client also returns this error for a fork HTTP 400 response without stream-not-supported. message says why.

NotSupported

interface NotSupported {
  readonly _tag: "NotSupported";
  readonly id: StreamId;
  readonly feature: string;
}

An operation fails with NotSupported when the host or the remote client does not support feature, for example fork, producer, or expected-offset. An append on the memory host or a storage host never fails with NotSupported.

InvalidReadRequest

interface InvalidReadRequest {
  readonly _tag: "InvalidReadRequest";
  readonly id: StreamId;
}

A read fails with InvalidReadRequest when the request is not valid, for example when the offset has the wrong format. message says why.

CreateConflictReason

type CreateConflictReason =
  "config-mismatch" | "soft-deleted" | "fork-content-type" | "fork-source-soft-deleted";

CreateConflictReason is the type of CreateConflict.reason.

ReasonMeaning
config-mismatchA stream with this id exists with another configuration
soft-deletedThe id belongs to a deleted stream
fork-content-typeThe fork asked for a content type that differs from the source
fork-source-soft-deletedThe source of the fork was deleted

Errors by operation

Each protocol operation fails with one of these unions. The methods of a stream class add faults to them, as listed under Failures.

HeadError

type HeadError = StreamNotFound | StreamGone;

head fails with HeadError.

ReadError

type ReadError = StreamNotFound | StreamGone | InvalidReadRequest;

read fails with ReadError.

ReadNextError

type ReadNextError = StreamNotFound | StreamGone | InvalidReadRequest | NotSupported;

readNext fails with ReadNextError. readNext is the protocol read that can wait for new data, and it adds NotSupported to ReadError.

CreateError

type CreateError =
  CreateConflict | InvalidCreateRequest | ForkSourceNotFound | InvalidForkRequest | NotSupported;

create and fork fail with CreateError.

AppendBaseError

type AppendBaseError =
  StreamNotFound | StreamGone | StreamClosed | StreamBusy | AppendConflict | NotSupported;

An append can fail with any AppendBaseError, whatever its options.

AppendError

type AppendError =
  | AppendBaseError
  | InvalidAppendRequest
  | OffsetMismatch
  | StaleEpoch
  | ProducerGap
  | InvalidEpochSeq;

AppendError lists every error that the protocol append can fail with.

AppendErrorFor

type NoOptions = AppendErrorFor<{}>;
// AppendBaseError

type Conditional = AppendErrorFor<{ expectedOffset: string }>;
// AppendBaseError | OffsetMismatch

type WithProducer = AppendErrorFor<{ producer: Producer.Position }>;
// AppendBaseError | StaleEpoch | ProducerGap

AppendErrorFor<O> lists the errors that an append with options of type O can fail with. It includes OffsetMismatch only when O has expectedOffset, and it includes StaleEpoch and ProducerGap only when O has producer. An optional property counts as set, so AppendErrorFor<AppendCallOptions> includes all three.

RemoveError

type RemoveError = StreamNotFound | StreamGone | StreamBusy;

remove fails with RemoveError.

ProtocolError

type ProtocolError = HeadError | ReadNextError | CreateError | AppendError | RemoveError;

ProtocolError is the union of every protocol error.

Guards

isProtocolError

declare function isProtocolError(error: { readonly _tag: string }): error is ProtocolError;

isProtocolError returns true when the _tag of error is the tag of a protocol error. The HTTP handlers use it to map every protocol error to its HTTP response in one place.

On this page