clockworklabs/SpacetimeDB · error · TypeError

There is already an HTTP handler with the name

Error message

There is already an HTTP handler with the name '${name}'

What it means

HTTP handlers have their own namespace, tracked separately from reducer/procedure/view names in `existingHttpHandlers`. `defineHttpHandler` throws this error when a second handler export registers the same name. It fires during module build when `registerHttpHandler` (called from the handler's `[registerExport]` hook) processes your exports.

Solutions

1. Rename one of the two handlers named in the error so each HTTP handler export name is unique.
2. Deduplicate barrel re-exports: keep the handler exported from exactly one module path.
3. Note handlers and reducers may share a name across namespaces, but keeping them distinct avoids confusion; the hard rule here is handler-vs-handler only.

Example fix

// before
export const health = spacetimedb.httpHandler(...);
export { health } from './handlers'; // duplicate registration

// after
export const health = spacetimedb.httpHandler(...);
export { health as healthProbe } from './handlers';

// Keep an explicit registry of handler names in one module.
const handlerNames = new Set<string>();
export function makeHandler(name: string, fn: any) {
  if (handlerNames.has(name)) throw new Error(`duplicate handler: ${name}`);
  handlerNames.add(name);
  return spacetimedb.httpHandler(/* ... */, fn);
}

When it happens

Trigger: Two `spacetimedb.httpHandler(...)` exports with the same export name; re-exporting a handler from a shared file plus defining a local one with the same name; barrel files duplicating a handler export into the entry module.

Common situations: Refactoring handlers into a library and re-exporting alongside an existing local handler; alias re-exports that keep the original name; two developers adding `health` handlers in different files that both get star-exported.

Related errors

• HTTP handler ' ' was exported more than once
• HTTP route for path ' ' refers to a handler that was not…
• There is already a reducer, procedure, or view with the name
• exporting something that is not a spacetime export
• multiple schemas are not supported

AI-assisted analysis of clockworklabs/SpacetimeDB@eddf9f5014 (2026-08-20). Data as JSON: /api/errors/c9157caed59a2f2a. Report an issue: GitHub.

Appendix: source

Thrown at crates/bindings-typescript/src/server/schema.ts:134

  submoduleDispatchInfos: SubmoduleDispatchInfo[] = [];

  constructor(getSchemaType: (ctx: SchemaInner<S>) => S) {
    super();
    this.schemaType = getSchemaType(this);
  }

  defineFunction(name: string) {
    if (this.existingFunctions.has(name)) {
      throw new TypeError(
        `There is already a reducer, procedure, or view with the name '${name}'`
      );
    }
    this.existingFunctions.add(name);
  }

  defineHttpHandler(name: string) {
    if (this.existingHttpHandlers.has(name)) {
      throw new TypeError(
        `There is already an HTTP handler with the name '${name}'`
      );
    }
    this.existingHttpHandlers.add(name);
  }

  resolveSchedules() {
    if (this.schedulesResolved) {
      return;
    }
    this.schedulesResolved = true;
    // Pending schedules come from two API paths:
    // - legacy table({ scheduled }) schedules already know their tableName and
    //   scheduleAtCol because schema() resolves them while iterating table keys
    // - reducer/procedure({ onSchedule }) schedules only know the table handle,
    //   so resolve them through tableSourceNames and reject duplicate table
    //   handle registrations because the target table name is ambiguous
    const scheduledTables = new Map<string, string>();

View on GitHub (pinned to eddf9f5014)