nocobase/nocobase · error

dataSourcesCollections.fields:apply requires dataSourceKey

Error message

dataSourcesCollections.fields:apply requires dataSourceKey

What it means

normalizeExternalFieldInput (used by the dataSourcesCollections.fields:apply flow for external data source fields) merges raw values with defaults and requires a dataSourceKey to know which data source the field belongs to. It throws when neither the submitted values nor the supplied defaults contain dataSourceKey.

Source

Thrown at packages/plugins/@nocobase/plugin-data-source-manager/src/server/services/external-field-apply.ts:73

      .map((name) => String(name).toLowerCase())
      .sort()
      .join('_'),
  );
}

export function normalizeExternalFieldInput(
  rawValues: any,
  defaults: {
    dataSourceKey?: string;
    collectionName?: string;
  },
) {
  const values = mergeSettings(rawValues) as any;
  const dataSourceKey = values.dataSourceKey || defaults.dataSourceKey;
  const collectionName = values.collectionName || defaults.collectionName;

  if (!dataSourceKey) {
    throw new Error('dataSourcesCollections.fields:apply requires dataSourceKey');
  }
  if (!collectionName) {
    throw new Error('dataSourcesCollections.fields:apply requires collectionName');
  }
  if (!values.name) {
    throw new Error('dataSourcesCollections.fields:apply requires name');
  }

  const interfaceType = values.interface;
  const type = values.type || RELATION_INTERFACE_TYPE_MAP[interfaceType];
  const normalized = {
    ...values,
    dataSourceKey,
    collectionName,
    type,
  };

  if (RELATION_TYPES.has(normalized.type)) {

View on GitHub (pinned to fa42722fef)

Solutions

1. Pass dataSourceKey in the values payload: { dataSourceKey: 'main', collectionName: 'users', name: 'age', ... }.
2. Supply the defaults argument: applyExternalFieldDefinition(ctx, values, { dataSourceKey, collectionName }).
3. Derive the key from the qualified collection name ('dataSourceKey.collectionName') using parseCollectionNameWithDataSourceKey and pass it along.

Example fix

// before
await applyExternalFieldDefinition(ctx, { collectionName: 'users', name: 'age', interface: 'number' });
// after
await applyExternalFieldDefinition(ctx, { collectionName: 'users', name: 'age', interface: 'number' }, { dataSourceKey: 'main' });

function assertApplyInput(values: Record<string, unknown>, defaults: Record<string, unknown>) {
  const merged = { ...defaults, ...values };
  if (!merged.dataSourceKey) throw new Error('fields:apply: dataSourceKey missing (values or defaults)');
}

function hasFieldApplyScope(v: unknown): v is { dataSourceKey: string; collectionName: string; name: string } {
  const o = v as any;
  return typeof o?.dataSourceKey === 'string' && o.dataSourceKey.length > 0;
}

try {
  await applyExternalFieldDefinition(ctx, values, defaults);
} catch (e) {
  if (e.message.includes('requires dataSourceKey')) {
    throw new Error(`Pass dataSourceKey via values or defaults; got values=${JSON.stringify(values)} defaults=${JSON.stringify(defaults)}`, { cause: e });
  }
  throw e;
}

When it happens

Trigger: Calling applyExternalFieldDefinition(values, defaults) or the fields:apply action where values.dataSourceKey and defaults.dataSourceKey are both undefined/empty — e.g. applying a field to an external collection without passing { dataSourceKey } or including dataSourceKey in values.

Common situations: Calling applyExternalFieldDefinition directly from server code without the defaults argument; a client action targeting an external collection that omits the dataSourceKey from filterByTk/context; copy-pasted field-apply calls between main-app and external-source code paths.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• dataSourcesCollections.fields:apply requires collectionName
• dataSourceKey is required
• dataSourcesCollections.fields:apply requires name
• Relation field ${normalized.name} requires target
• "${name}" is required

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