What causes "Authentication token not specified" in hcengineering/platform?

Obtain a valid token and pass it as the second argument: `getClient(paymentUrl, token)`.

Authentication token not specified

Error message

Authentication token not specified

What it means

The `getClient` factory in payment-client throws this Error when the token argument is undefined, null, or an empty string. All payment API calls require an authentication token, so the factory refuses to construct a client without one. This fail-fast validation prevents unauthenticated requests from ever being issued.

Source

Thrown at packages/payment-client/src/client.ts:31

// limitations under the License.
//

import { concatLink, type WorkspaceUuid } from '@hcengineering/core'
import { CheckoutResponse, SubscribeRequest, CheckoutStatus, SubscriptionData } from './types'
import { PaymentError, NetworkError } from './error'

/**
 * Create a payment client instance
 * @param paymentUrl - URL of the payment service
 * @param token - Authentication token
 * @returns PaymentClient instance
 */
export function getClient (paymentUrl?: string, token?: string): PaymentClient {
  if (paymentUrl === undefined || paymentUrl == null || paymentUrl === '') {
    throw new Error('Payment service URL not specified')
  }
  if (token === undefined || token == null || token === '') {
    throw new Error('Authentication token not specified')
  }

  return new PaymentClient(paymentUrl, token)
}

/**
 * Payment service client
 * Handles all subscription and payment operations
 */
export class PaymentClient {
  private readonly headers: Record<string, string>

  constructor (
    private readonly endpoint: string,
    private readonly token: string
  ) {
    this.headers = {
      Authorization: 'Bearer ' + token,

View on GitHub (pinned to 63e28dc964)

Solutions

Obtain a valid token and pass it as the second argument: `getClient(paymentUrl, token)`.
Ensure the token's environment variable or secret is present in the deployment environment.
Check the upstream process that fetches/refreshes the token — it may have failed and produced an empty string.
Log/inspect the token presence (not its value) before calling getClient to catch empty tokens early.

Example fix

// before
const client = getClient(url, process.env.PAYMENT_TOKEN)
// after
if (!process.env.PAYMENT_TOKEN) throw new Error('PAYMENT_TOKEN env var required')
const client = getClient(url, process.env.PAYMENT_TOKEN)

Defensive patterns

Strategy: validation

Validate before calling

function assertToken(token: string | undefined | null): asserts token is string {
  if (token == null || token === '') throw new Error('Payment token missing — check PAYMENT_TOKEN')
}
assertToken(process.env.PAYMENT_TOKEN)
const client = getClient(paymentUrl, process.env.PAYMENT_TOKEN as string)

Type guard

function hasToken(t: unknown): t is string {
  return typeof t === 'string' && t.trim() !== ''
}

Try / catch

try {
  const client = getClient(url, token)
} catch (e) {
  if ((e as Error).message === 'Authentication token not specified') {
    throw new Error('Config error: payment token missing — refresh credentials')
  }
  throw e
}

Prevention

Verify token retrieval/refresh steps actually populated the token before client creation.
Mount secrets correctly in containers and check secret presence at startup.
Never default tokens to empty strings; treat them as required config.

When it happens

Trigger: Calling `getClient(paymentUrl)` with only a URL, or `getClient(paymentUrl, '')` / `getClient(paymentUrl, undefined)` — the token env var or credential store returned nothing.

Common situations: Missing auth token env var (e.g. PAYMENT_TOKEN), expired token that was cleared from a secret store, secret not mounted in the container, or the login/token-fetch step upstream failed silently.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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