paperclipai/paperclip · error

${name} must be "true" or "false", got: ${env[name]}

Error message

${name} must be "true" or "false", got: ${env[name]}

What it means

Environment-variable parsing guard in the DB client bootstrap: a boolean-typed env var (e.g. pool prepare toggle) was set to a value other than true/1/false/0, so the driver option cannot be derived and startup aborts naming the variable and its raw value.

Source

Thrown at packages/db/src/client.ts:77

  const ref = new WeakRef(client);
  let refs = clientsByHostPort.get(key);
  if (!refs) {
    refs = new Set();
    clientsByHostPort.set(key, refs);
  }
  refs.add(ref);
  clientFinalizer.register(client, { hostPortKey: key, ref }, ref);
}

/**
 * Ends every live client `createDb` handed out for the given URL's host and
 * port, then forgets them. Call this before stopping a Postgres cluster: a
 * client that outlives the cluster it points at can crash the process (a
 * reserved connection's deferred write firing after the socket is gone).
 * Swallows individual `end()` errors so one bad client cannot block the rest.
 */
export async function closeRegisteredClients(url: string): Promise<void> {
  const key = hostPortKey(url);
  const refs = clientsByHostPort.get(key);
  if (!refs) return;

  clientsByHostPort.delete(key);
  const clients: RegisteredPostgresClient[] = [];
  for (const ref of refs) {
    clientFinalizer.unregister(ref);
    const client = ref.deref();
    if (client) clients.push(client);
  }

  await Promise.all(clients.map((client) => client.end({ timeout: 1 }).catch(() => {})));
}

function isSafeIdentifier(value: string): boolean {
  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
}

View on GitHub (pinned to 01ad858492)

Solutions

1. Set ${name} to "true" or "false".

When it happens

Trigger: Thrown at packages/db/src/client.ts:70 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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