What causes "Payment service URL not specified" in hcengineering/platform?

Pass the actual payment service URL as the first argument, e.g. `getClient('https://payments.example.com', token)`.

Payment service URL not specified

Error message

Payment service URL not specified

What it means

The payment-client package exposes a `getClient` factory that validates its arguments and throws this Error when paymentUrl is undefined, null, or an empty string. The factory refuses to build a PaymentClient without a service endpoint since every subsequent call would fail. It fails fast so misconfiguration is caught at client-creation time.

Source

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

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//
// See the License for the specific language governing permissions and
// 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

View on GitHub (pinned to 63e28dc964)

Solutions

Pass the actual payment service URL as the first argument, e.g. `getClient('https://payments.example.com', token)`.
Ensure the environment variable feeding paymentUrl (e.g. PAYMENT_URL) is set in the runtime environment.
Check the call site for a wrong-order argument mistake (URL vs token swapped).

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

function assertPaymentUrl(url: string | undefined | null): asserts url is string {
  if (url == null || url === '') throw new Error('PAYMENT_URL must be set before creating payment client')
}
assertPaymentUrl(process.env.PAYMENT_URL)
const client = getClient(process.env.PAYMENT_URL as string, token)

Type guard

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

Try / catch

try {
  const client = getClient(url, token)
} catch (e) {
  if ((e as Error).message === 'Payment service URL not specified') {
    throw new Error('Config error: PAYMENT_URL missing')
  }
  throw e
}

Prevention

Load and validate payment config at startup with a schema validator.
Keep URL and token argument order consistent; prefer an options object at the call site.
Fail fast in CI/startup checks when required env vars are absent.

When it happens

Trigger: Calling `getClient()` with no arguments, or `getClient(undefined, token)` / `getClient('', token)` — typically when the payment service URL config or env var is missing.

Common situations: PAYMENT_URL environment variable not set in a deployment, forgotten config entry, or code refactored to pass the URL dynamically where the value became empty.

Related errors

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