"'' is not a function" - React State, Capnweb and You

[SamJB123]

Writing this in the hopes I rescue at least one person from what I spent the last 6 hours debugging.

Cap'n Web + React: Avoid the '' is not a function Trap

This note documents a subtle failure mode we hit while building an API between browsers and Durable Objects with Cap'n Web. It can affect any React-driven client that stores a Cap'n Web stub returned from RpcSession#getRemoteMain().

Where the Problem Shows Up

const [stub, setStub] = useState<RpcStub<MyApi> | null>(null)

const connect = async () => {
  const session = new RpcSession(transport, null)
  const remote = session.getRemoteMain() as RpcStub<MyApi>

  // ⚠️ BUG: React sees `remote` is a function and treats this as an updater
  setStub(remote)
}

React checks the type of the argument passed to setStub. If it is a function, it assumes you are providing a state updater (setState(prev => next)) and invokes it immediately with the previous value (prev). Cap'n Web stubs are proxies masquerading as callables, so React triggers a bogus remote invocation with the previous stub value (often null). That leads to wire messages like:

["pipeline",0,[],[null]]

…which fail inside Cap'n Web with the familiar:

TypeError: '' is not a function.

On the surface it looks like a Cap'n Web or transport bug, but the real issue is the React state API mistaking the stub for an updater.

The Fix

Always wrap callable stubs (or any other function-like values) in a function when passing them to a React setter:

setStub(() => remote)

This version passes a function that returns the stub instead of the stub itself. React now treats it as “updater returning new state” and does not execute the stub.

Symptoms & Diagnosis Checklist

• UI shows TypeError: '' is not a function. whenever a Cap'n Web method is invoked.
• Server logs contain ["pipeline",0,[],[null]] followed by a release of the same import id.
• No errors appear in the client or server consoles besides the Cap'n Web dispatch failure.
• You’re using React state to hold the stub (common in hooks/demos).

If those conditions match, check your setState call.

Quick Reference

Do this	Not this
setCapnwebStub(() => remoteStub)	setCapnwebStub(remoteStub)

Why Document This Here?

Browser-facing uses of Cap'n web that use React can easily rely on Cap'n Web stubs inside React components or hooks, intentionally or by accident. Anyone using Cap'n Web to connect users to back-ends could experience the same failure mode. This guide captures the root cause and its fix so others can avoid the six-hour debugging session that this author experienced to solve this problem!

[kentonv]

I actually ran into this myself in a project I'm working on.

My solution was to wrap it in an object, that this, setState({stub: remote}). This way the type system can catch mistakes, I suppose.