What causes "VariablesProvider: ${variableName} is not found" in nocobase/nocobase?

Ensure the provider supplying that variable (e.g. the source record block's VariablesProvider) is mounted and initialized before dependents resolve it.

nocobase/nocobase · error

VariablesProvider: ${variableName} is not found

Error message

VariablesProvider: ${variableName} is not found

What it means

VariablesProvider's getResult resolves a variable path like 'currentUser.nickname' by splitting on '.' and requiring the root variable name to exist as a key in the current variables context. If the top-level variable is absent from the context (not registered yet or never provided), resolution aborts with this error naming the missing variable.

Source

Thrown at packages/core/client/src/variables/VariablesProvider.tsx:145

         */
        fieldOperator?: string | void;
      },
    ) => {
      const list = variablePath.split('.');
      const variableName = list[0];
      const _variableToCollectionName = mergeVariableToCollectionNameWithLocalVariables(variablesStore, localVariables);
      let current = mergeCtxWithLocalVariables(ctxRef.current, localVariables);
      const { fieldPath, dataSource, variableOption } = getFieldPath(variableName, _variableToCollectionName);
      let collectionName = fieldPath;

      const { fieldPath: fieldPathOfVariable } = getFieldPath(variablePath, _variableToCollectionName);
      const collectionNameOfVariable =
        list.length === 1
          ? variableOption?.collectionName
          : getCollectionJoinField(fieldPathOfVariable, dataSource)?.target;

      if (!(variableName in current)) {
        throw new Error(`VariablesProvider: ${variableName} is not found`);
      }

      for (let index = 0; index < list.length; index++) {
        if (current == null) {
          return {
            value: current === undefined ? variableOption?.defaultValue : current,
            dataSource,
            collectionName: collectionNameOfVariable,
          };
        }

        if (_.isFunction(current)) {
          break;
        }

        const key = list[index];
        const currentVariablePath = list.slice(0, index + 1).join('.');
        const { fieldPath } = getFieldPath(currentVariablePath, _variableToCollectionName);

View on GitHub (pinned to fa42722fef)

Solutions

Ensure the provider supplying that variable (e.g. the source record block's VariablesProvider) is mounted and initialized before dependents resolve it.
Check the variable name in the path matches a registered variable exactly (case-sensitive).
Use the optional-chaining style variable expression or a default value so missing variables resolve gracefully where supported.
Wrap dependent rendering in a VariablesProvider that includes the variable, or register it via useVariablesContextAction/setCtx.

Example fix

// before
const { result } = useVariable('$$currentUser.nickname'); // currentUser not in ctx
// after
if ('$currentUser' in variablesCtx) {
  const { result } = useVariable('$$currentUser.nickname');
} else {
  return null; // or fallback value
}

Defensive patterns

Strategy: try-catch

Validate before calling

const rootName = variablePath.split('.')[0];
if (!(rootName in variablesContext)) {
  return fallbackValue; // variable not registered yet
}

Type guard

function variableExists(ctx: Record<string, unknown>, path: string): boolean {
  const root = path.split('.')[0];
  return root in (ctx ?? {});
}

Try / catch

try {
  const { result } = await parseVariable(variablePath);
  return result;
} catch (e) {
  if (e instanceof Error && e.message.startsWith('VariablesProvider:')) {
    return variableOption?.defaultValue ?? null; // graceful fallback
  }
  throw e;
}

Prevention

Wrap consumers in a VariablesProvider that registers the variable before children resolve.
Double-check variable name spelling/case in settings UIs.
Provide defaultValue on variable options so missing roots degrade gracefully.
Re-render dependents after setCtx registers new variables.

When it happens

Trigger: Rendering a component whose default value / settings reference `$variablesName.field` while `variablesName` is not registered in the VariablesProvider context — e.g. the variable provider that supplies it hasn't mounted, the variable name was renamed, or the path's root doesn't match any registered variable/local variable.

Common situations: Using a variable in a form field default value before the upstream block providing it is loaded; typos or renames in variable names; variables set via setCtx after children already attempted resolution; deleting a collection/field that previously fed a variable.

Related errors

AI-assisted analysis of nocobase/nocobase@fa42722fef (2026-09-01). Data as JSON: /api/errors/2f4a822ff9248cb2. Report an issue: GitHub.