{"record":{"id":"6e50ff1b8842cb0f","repo":"hcengineering/platform","slug":"key-value-api-url-not-specified","errorCode":null,"errorMessage":"Key-value API URL not specified","messagePattern":"Key-value API URL not specified","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/kvs-client/src/client.ts","lineNumber":30,"sourceCode":"// See the License for the specific language governing permissions and\n// limitations under the License.\n//\nimport { concatLink } from '@hcengineering/core'\nimport { PlatformError } from '@hcengineering/platform'\nimport { KeyValueClient, ListResult } from './types'\n\n/**\n * Get a KeyValueClient instance\n * @param namespace - Namespace for the key-value operations\n * @param baseUrl - URL of the key-value API server\n * @param token - Optional authorization token\n * @param retryTimeoutMs - Optional timeout for retrying failed requests\n * @returns KeyValueClient instance\n * @public\n */\nexport function getClient (namespace: string, baseUrl: string, token?: string, retryTimeoutMs?: number): KeyValueClient {\n  if (baseUrl === undefined) {\n    throw new Error('Key-value API URL not specified')\n  }\n\n  return new KeyValueClientImpl(namespace, baseUrl, token, retryTimeoutMs)\n}\n\nclass KeyValueClientImpl implements KeyValueClient {\n  private readonly requestInit: RequestInit\n\n  constructor (\n    private readonly namespace: string,\n    private readonly baseUrl: string,\n    private readonly token?: string,\n    private readonly retryTimeoutMs: number = 5000\n  ) {\n    if (baseUrl === '') {\n      throw new Error('Key-value API URL not specified')\n    }\n","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/packages/kvs-client/src/client.ts#L12-L48","documentation":"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.","triggerScenarios":"getClient(namespace, undefined /* or unset variable */) — baseUrl resolves to undefined at runtime.","commonSituations":"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.","solutions":["Set the KVS base URL environment variable or config value used by the caller.","Pass an explicit, non-empty URL string to getClient.","Add a startup-time config validation to fail fast when the URL is missing.","Check the deployment/CI environment actually injects the variable."],"exampleFix":"// before\nconst client = getClient('mynamespace', process.env.KVS_URL)\n// after\nconst baseUrl = process.env.KVS_URL\nif (baseUrl == null || baseUrl === '') {\n  throw new Error('KVS_URL environment variable is required')\n}\nconst client = getClient('mynamespace', baseUrl)","handlingStrategy":"validation","validationCode":"if (!process.env.KVS_URL) throw new Error('KVS_URL must be set before initializing the KVS client')","typeGuard":null,"tryCatchPattern":"let client: KeyValueClient\ntry {\n  client = getClient('ns', baseUrl!)\n} catch (err) {\n  if (err instanceof Error && err.message.includes('Key-value API URL not specified')) {\n    // fail fast with a config guidance message\n  }\n  throw err\n}","preventionTips":["Validate all required service URLs at process startup, before serving traffic.","Document required environment variables in deployment config templates.","Never pass possibly-undefined config values without a runtime check."],"tags":["configuration","missing-env-var","kvs"],"backgroundTag":"missing-env-var","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}