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.

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
• Payment provider is not configured. Please provide payment…
• Please provide email service url
• Please provide front url
• SMTP config is required for custom transporter

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

Appendix: 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)