paperclipai/paperclip · error

turnStartTimeoutMs must be a positive safe integer

Error message

turnStartTimeoutMs must be a positive safe integer

What it means

Options guard in #startTurn of the runnerd Codex transport: the configured turnStartTimeoutMs (default 30000) is not a positive safe integer. This is a configuration error in the transport options object, validated before any turn is started.

Source

Thrown at packages/paperclip-runner/src/live/runnerd-codex-transport.ts:5299

        },
        ...(call.sourceEventId && call.sourceEventType
          ? {
              paperclipTrace: {
                sourceEventId: call.sourceEventId,
                sourceEventType: call.sourceEventType,
              },
            }
          : {}),
      }),
    );
  }

  async #startTurn(
    params: Record<string, unknown>,
  ): Promise<Record<string, unknown>> {
    const turnStartTimeoutMs = this.options.turnStartTimeoutMs ?? 30_000;
    if (!Number.isSafeInteger(turnStartTimeoutMs) || turnStartTimeoutMs <= 0) {
      throw new Error("turnStartTimeoutMs must be a positive safe integer");
    }
    const commandDeadline = Date.now() + turnStartTimeoutMs;
    const input = Array.isArray(params.input) ? params.input.map(record) : [];
    const message = input
      .map((item) => (typeof item.text === "string" ? item.text : ""))
      .join("\n");
    const pendingTurnId = `turn_lab_${randomUUID().replaceAll("-", "")}`;
    this.#turnId = pendingTurnId;
    const responseEpoch = ++this.#turnStartResponseEpoch;
    this.#turnStartAdmission?.resolve(false);
    let resolveAdmission!: (accepted: boolean) => void;
    this.#turnStartAdmission = {
      settled: new Promise((resolve) => {
        resolveAdmission = resolve;
      }),
      resolve: (accepted) => resolveAdmission(accepted),
    };
    this.#turnStartResponsePending = true;

View on GitHub (pinned to 01ad858492)

Solutions

1. Set turnStartTimeoutMs to a positive integer below Number.MAX_SAFE_INTEGER
2. Remove the option to use the 30s default
3. Fix the config source that produced NaN, zero, negative, or fractional values

When it happens

Trigger: Thrown at packages/paperclip-runner/src/live/runnerd-codex-transport.ts:5299 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/e9ba9582e67472e8. Report an issue: GitHub.