Error Catalog

Every plugin raises tagged errors with a _tag discriminator. Effect.catchTag and Effect.catchTags match on the literal tag string. Most plugins also carry a phase field that identifies which stage of the lifecycle raised, so consumers can pin behavior by tag + phase rather than by message substring.

This catalog lists the tags exported from each plugin. The fields shown are the discriminator slots you match on; full shapes and the helper constructors live in each plugin's errors.ts.

Account

• AccountAcquireError — phase: 'validate-name' | 'validate-funding' | 'decode-inline' | 'bind-signer' | 'generate-keypair' | 'derive-address' | …. Surfaces during account boot.
• AccountSignError — phase: 'build-tx' | 'sign' | 'submit' | 'no-digest' | 'await-finality' | 'dependent-package-not-found'. Surfaces when an account-bound sign attempt fails.

Action

• ActionError — phase: 'discriminator' | 'build' | 'sign' | 'execute-failed' | 'verify'. Single tag covers all action(...) failure paths.

Coin

• CoinError — phase: 'not-found' | 'ambiguous' | 'nested-generic' | 'cap-missing' | 'metadata-fetch' | 'mint-tx'. Surfaces when a coin.fromPackage or coin.known reference cannot be resolved or minted.

DeepBook

• DeepbookPluginError — phase: 'image-pull' | 'network' | 'publish' | 'create-pools' | 'pyth-publish' | 'pyth-feed'. Local-mode boot and pool seeding.
• DeepbookConfigError — invalid deepbook(...) options.
• ForkIncompatibleError — fork mode rejected an incompatible reference.

Faucet

• FaucetUnreachable — transport-level (ECONNREFUSED, DNS, TLS, AbortSignal timeout).
• FaucetExhausted — the wall-clock budget ran out before a funding attempt landed. Carries attempts: number and the underlying lastCause. If the attempt cap is reached first, the last FaucetUnreachable | FaucetBodyError is re-raised verbatim; only a wall-clock timeout surfaces as FaucetExhausted.
• FaucetBodyError — reason: 'failure-status' | 'invalid-json'. A 200 OK carrying { status: { Failure } } surfaces here rather than being treated as success.
• FaucetConfigError — invalid strategy config.

The "no strategy registered for this chain" case is not a faucet-plugin tag — it surfaces as the substrate StrategyNotFoundError (see Substrate).

Host service

• HostServiceConfigError — invalid hostService(...) options.
• HostServiceAcquireError — phase: 'allocate-port' | 'spawn' | 'ready' | 'exit'. Surfaces during dev-server boot and ready-probing.

Package

• PublishError — phase: 'hash' | 'scrub' | 'build' | 'publish-tx' | 'parse' | 'verify'. Single tag covers the full localPackage(...) publish path.

Seal

• SealError — phase: 'port-alloc' | 'image' | 'keygen' | 'publish' | 'register' | 'config-render'. Local-keygen boot.
• SealConfigError — invalid seal(...) options.
• ForkIncompatibleError — fork-mode reference mismatch.

Sui

• SuiPluginError — phase: 'image-build' | 'port-allocate' | 'container-start' | 'grpc-probe' | 'faucet-probe' | 'graphql-probe'. Localnet boot.
• SuiConfigError — invalid sui(...) options.
• SuiCliError — op-tagged failure from a Sui CLI shell-out.
• ForkUnsupportedError — fork mode rejected an unsupported request.

Wallet

• WalletBootError — phase: 'listen' | 'allocate-port' | 'read-token' | 'write-token' | 'bind-account' | 'route-url' | …. Dev-wallet boot.
• WalletRequestError — phase: 'origin-missing' | 'origin-forbidden' | 'unauthorized' | 'route-not-found' | 'address-not-found' | 'body-invalid' | …. Per-request rejections inside the running wallet.

Walrus

• WalrusPluginError — phase: 'image-build' | 'cluster-network' | 'deploy' | 'exchange' | 'storage-node' | 'proxy'. Local-mode boot.
• WalrusConfigError — invalid walrus(...) options.
• ForkIncompatibleError — fork-mode reference mismatch.

Substrate

Errors raised by the shared substrate runtime rather than a single plugin. The one app-facing tag:

• StrategyNotFoundError — no funding strategy is registered for the requested capability key. Carries capabilityKey and registeredKeys so the renderer can report the requested key against the registered ones. A missing SUI faucet strategy surfaces here; there is no Faucet-prefixed strategy-missing tag.

Catching errors in app code

import { Effect } from 'effect';

const program = someEffect.pipe(
	Effect.catchTags({
		AccountAcquireError: (err) => Effect.logError(`account boot failed at phase ${err.phase}`),
		FaucetExhausted: (err) => Effect.logError(`faucet gave up after ${err.attempts} attempts`),
	}),
);

Plugin-author code that catches its own union should use Effect.catchTag for single-tag handling and catchTags for the multi-tag form; both narrow on the literal _tag discriminator.