hcengineering/platform · error · Error

Namespace not specified

Error message

Namespace not specified

What it means

The KvsClient constructor throws this Error when the namespace parameter is an empty string or undefined. Every key-value operation is scoped to a namespace, so the client refuses to initialize without one. Fail-fast behavior surfaces configuration mistakes immediately instead of producing requests to the wrong or nonexistent namespace.

Source

Thrown at packages/kvs-client/src/client.ts:50

  return new KeyValueClientImpl(namespace, baseUrl, token, retryTimeoutMs)
}

class KeyValueClientImpl implements KeyValueClient {
  private readonly requestInit: RequestInit

  constructor (
    private readonly namespace: string,
    private readonly baseUrl: string,
    private readonly token?: string,
    private readonly retryTimeoutMs: number = 5000
  ) {
    if (baseUrl === '') {
      throw new Error('Key-value API URL not specified')
    }

    if (namespace === '' || namespace === undefined) {
      throw new Error('Namespace not specified')
    }

    const isBrowser = typeof window !== 'undefined'

    this.requestInit = {
      keepalive: true,
      headers: {
        ...(this.token === undefined
          ? {}
          : {
              Authorization: 'Bearer ' + this.token
            })
      },
      ...(isBrowser ? { credentials: 'include' } : {})
    }
  }

  async setValue<T>(key: string, value: T): Promise<void> {

View on GitHub (pinned to 63e28dc964)

Solutions

1. Pass a concrete non-empty namespace string as the first constructor argument, e.g. `new KvsClient('my-app', baseUrl)`.
2. Verify the source of the namespace (env var/config) actually contains a value at startup.
3. Validate the namespace before constructing: `if (!ns) throw new Error('namespace required')`.

Example fix

// before
const client = new KvsClient(config.namespace ?? '', baseUrl)
// after
if (!config.namespace) throw new Error('KVS namespace is required')
const client = new KvsClient(config.namespace, baseUrl)

function assertNamespace(ns: string | undefined): asserts ns is string {
  if (typeof ns !== 'string' || ns === '') throw new Error('KVS namespace must be a non-empty string')
}
assertNamespace(config.namespace)
const client = new KvsClient(config.namespace, baseUrl)

function isValidNamespace(ns: unknown): ns is string {
  return typeof ns === 'string' && ns.length > 0
}

try {
  const client = new KvsClient(ns, url)
} catch (e) {
  if ((e as Error).message === 'Namespace not specified') {
    throw new Error('Configuration error: KVS namespace missing — check config/env')
  }
  throw e
}

When it happens

Trigger: `new KvsClient('', baseUrl)` or `new KvsClient(undefined as any, baseUrl)` — an empty/undefined namespace passed to the constructor.

Common situations: Namespace sourced from an unset environment variable or optional config field, copy-pasted client setup where the namespace argument was left blank, or a refactor that renamed the config key feeding the namespace.

Related errors

• Ticks per second has an invalid value: must be >= 1 && <= 10
• Key-value API URL not specified
• No screen access granted
• Unable to find ${RUSH_JSON_FILENAME}.
• Accounts url not specified

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/ee99d411c2aff04d. Report an issue: GitHub.