jquense/yup · error · TypeError

ref must be a non-empty string

Error message

ref must be a non-empty string

What it means

After trimming, a Reference key must still contain characters — an empty (or whitespace-only) string points nowhere, so the constructor rejects it. This is a sibling check to the type check: the key was a string but had no meaningful content. Thrown at construction time with the message 'ref must be a non-empty string'.

Source

Thrown at src/Reference.ts:38

export default class Reference<TValue = unknown> {
  readonly key: string;
  readonly isContext: boolean;
  readonly isValue: boolean;
  readonly isSibling: boolean;
  readonly path: any;

  readonly getter: (data: unknown) => unknown;
  readonly map?: (value: unknown) => TValue;

  declare readonly __isYupRef: boolean;

  constructor(key: string, options: ReferenceOptions<TValue> = {}) {
    if (typeof key !== 'string')
      throw new TypeError('ref must be a string, got: ' + key);

    this.key = key.trim();

    if (key === '') throw new TypeError('ref must be a non-empty string');

    this.isContext = this.key[0] === prefixes.context;
    this.isValue = this.key[0] === prefixes.value;
    this.isSibling = !this.isContext && !this.isValue;

    let prefix = this.isContext
      ? prefixes.context
      : this.isValue
      ? prefixes.value
      : '';

    this.path = this.key.slice(prefix.length);
    this.getter = this.path && getter(this.path, true);
    this.map = options.map;
  }

  getValue(value: any, parent?: {}, context?: {}): TValue {
    let result = this.isContext ? context : this.isValue ? value : parent;

View on GitHub (pinned to ff31eee8a2)

Solutions

1. Provide the actual field name, e.g. yup.ref('endDate').
2. Validate/fall back on the path before constructing: if (!path) throw or use a default.
3. Check upstream data (config, form, API) for empty strings feeding the ref.

Example fix

// before
yup.ref(config.targetPath ?? '')
// after
if (!config.targetPath) throw new Error('targetPath is required');
yup.ref(config.targetPath)

const refFrom = (path) => {
  if (typeof path !== 'string' || path.trim() === '') throw new Error('ref path required');
  return yup.ref(path);
};

const isNonEmptyString = (v) => typeof v === 'string' && v.trim().length > 0;

When it happens

Trigger: yup.ref('') or yup.ref(' ') — a whitespace-only string passes the typeof check but fails after `this.key = key.trim()`.

Common situations: Path variables from empty config values, empty form field names, split/join logic producing '' (e.g. ''.split('.') — though '' passes typeof), API responses with missing path fields.

Related errors

• ref must be a string, got:
• A Method name must be provided
• Method function must be provided
• either `then:` or `otherwise:` is required for `when()` cond
• conditions must return a schema object

AI-assisted analysis of jquense/yup@ff31eee8a2 (2026-08-31). Data as JSON: /api/errors/2f44c9de180d044a. Report an issue: GitHub.