hcengineering/platform · error · Error

Key-value API URL not specified

Error message

Key-value API URL not specified

What it means

The KVS client factory getClient requires a base URL for the key-value API. Although the signature types baseUrl as string, a runtime check throws if it is undefined, catching callers who pass an unset config/environment value. No HTTP call is ever attempted in this case.

Source

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

// See the License for the specific language governing permissions and
// limitations under the License.
//
import { concatLink } from '@hcengineering/core'
import { PlatformError } from '@hcengineering/platform'
import { KeyValueClient, ListResult } from './types'

/**
 * Get a KeyValueClient instance
 * @param namespace - Namespace for the key-value operations
 * @param baseUrl - URL of the key-value API server
 * @param token - Optional authorization token
 * @param retryTimeoutMs - Optional timeout for retrying failed requests
 * @returns KeyValueClient instance
 * @public
 */
export function getClient (namespace: string, baseUrl: string, token?: string, retryTimeoutMs?: number): KeyValueClient {
  if (baseUrl === undefined) {
    throw new Error('Key-value API URL not specified')
  }

  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')
    }

View on GitHub (pinned to 63e28dc964)

Solutions

1. Set the KVS base URL environment variable or config value used by the caller.
2. Pass an explicit, non-empty URL string to getClient.
3. Add a startup-time config validation to fail fast when the URL is missing.
4. Check the deployment/CI environment actually injects the variable.

Example fix

// before
const client = getClient('mynamespace', process.env.KVS_URL)
// after
const baseUrl = process.env.KVS_URL
if (baseUrl == null || baseUrl === '') {
  throw new Error('KVS_URL environment variable is required')
}
const client = getClient('mynamespace', baseUrl)

if (!process.env.KVS_URL) throw new Error('KVS_URL must be set before initializing the KVS client')

let client: KeyValueClient
try {
  client = getClient('ns', baseUrl!)
} catch (err) {
  if (err instanceof Error && err.message.includes('Key-value API URL not specified')) {
    // fail fast with a config guidance message
  }
  throw err
}

When it happens

Trigger: getClient(namespace, undefined /* or unset variable */) — baseUrl resolves to undefined at runtime.

Common situations: Missing KVS_SERVICE_URL (or similar) environment variable; config object key miss; TypeScript compiled with a `string | undefined` value narrowed incorrectly; secret/config not injected in the deployment.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Namespace not specified
• Please provide email service url
• Please provide front url
• SMTP config is required for custom transporter
• Payment provider is not configured. Please provide payment p

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