> ## Documentation Index
> Fetch the complete documentation index at: https://eo.utopy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues when using effect-orpc.

## TypeScript says a service is missing

The handler yielded a service that has not been provided by the builder, a request-scoped provider, or the runtime passed to `makeEffectORPC`.

```ts title="fix.ts" theme={null}
const procedure = eos.provide(UsersRepoLive).effect(function* () {
  const usersRepo = yield* UsersRepo;
  return yield* usersRepo.list();
});
```

If the service is request-scoped, provide it from context:

```ts title="request-scoped-fix.ts" theme={null}
const procedure = eos
  .$context<{ user: User }>()
  .provide(CurrentUser, ({ context }) => Effect.succeed(context.user));
```

## A tagged error is not typed on the client

Make sure the tagged error class is registered in `.errors(...)` or in the `eoc.errors(...)` contract definition.

```ts title="error-registration.ts" theme={null}
const procedure = eos.errors({ UserNotFoundError });
```

## Request-local logs or annotations disappear

If request-local Effect context is created outside the oRPC pipeline in Node, use the Node bridge.

```ts title="node-bridge.ts" theme={null}
import { withFiberContext } from "effect-orpc/node";
```

See [Node context bridge](/effect-v4/guides/node-fiber-context).

## Scoped resources are recreated too often

Use a caller-owned `ManagedRuntime` for long-lived scoped resources.

```ts title="runtime.ts" theme={null}
const runtime = ManagedRuntime.make(AppLive);
const procedure = makeEffectORPC(runtime);
```

Dispose the runtime during application shutdown.

## Native middleware split my Effect pipeline

Native oRPC middleware can split contiguous Effect steps into multiple runtime boundaries.

Prefer Effect middleware when the middleware needs Effect context. If you must use native middleware and need request-local Effect context continuity in Node, import the Node bridge.

## Where to look next

<CardGroup cols={2}>
  <Card title="Mental model" icon="brain" href="/effect-v4/getting-started/mental-model">
    Review the main runtime and builder concepts.
  </Card>

  <Card title="Runtime management" icon="server-cog" href="/effect-v4/capabilities/runtime-management">
    Choose between layers and caller-owned runtimes.
  </Card>
</CardGroup>