nocobase/nocobase · error

dataSource ${values.dataSourceKey} not found

Error message

dataSource ${values.dataSourceKey} not found

What it means

applyExternalFieldDefinition looks up the data source by key in ctx.app.dataSourceManager.dataSources after validation and throws when it is not registered. Unlike the list action, there is no loading-state handling here — an unregistered key (never created, misconfigured, or its registration failed) results in this error before any field work happens.

Source

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

    .collectionManager.getCollection(values.collectionName)
    .getField(values.name)?.options;
}

export async function applyExternalFieldDefinition(
  ctx,
  rawValues: any,
  defaults: {
    dataSourceKey?: string;
    collectionName?: string;
  } = {},
) {
  const values = normalizeExternalFieldInput(rawValues, defaults);

  validateExternalRelationField(values);

  const dataSource = ctx.app.dataSourceManager.dataSources.get(values.dataSourceKey);
  if (!dataSource) {
    throw new Error(`dataSource ${values.dataSourceKey} not found`);
  }
  const collection = dataSource.collectionManager.getCollection(values.collectionName);
  if (!collection) {
    throw new Error(`collection ${values.collectionName} not found in dataSource ${values.dataSourceKey}`);
  }

  const repository = ctx.app.db.getRepository('dataSourcesFields');
  const filter = {
    name: values.name,
    collectionName: values.collectionName,
    dataSourceKey: values.dataSourceKey,
  };
  const existing = await repository.findOne({ filter });

  if (existing) {
    await repository.update({
      filter,
      values,

View on GitHub (pinned to fa42722fef)

Solutions

1. Verify the key exists: check ctx.app.dataSourceManager.dataSources keys or the dataSources collection, and fix the dataSourceKey in the call.
2. Run the apply after app startup completes and external data sources are loaded, not during bootstrap.
3. Re-enable/reinstall the data source plugin or recreate the data source if it was removed.

Example fix

// before
await applyExternalFieldDefinition(ctx, values, { dataSourceKey: 'mysql2' });  // not registered
// after
const key = [...ctx.app.dataSourceManager.dataSources.keys()].find((k) => k.includes('mysql'));
await applyExternalFieldDefinition(ctx, values, { dataSourceKey: key });

function assertDataSourceRegistered(app: any, key: string) {
  if (!app.dataSourceManager.dataSources.has(key)) {
    throw new Error(`dataSource '${key}' not registered; known keys: ${[...app.dataSourceManager.dataSources.keys()].join(', ')}`);
  }
}

function getRegisteredDataSource(app: any, key: unknown) {
  const ds = typeof key === 'string' ? app.dataSourceManager.dataSources.get(key) : undefined;
  return ds ?? null; // null means the apply call would throw — resolve key first
}

try {
  await applyExternalFieldDefinition(ctx, values, defaults);
} catch (e) {
  if (/^dataSource .* not found$/.test(e.message)) {
    const keys = [...ctx.app.dataSourceManager.dataSources.keys()];
    throw new Error(`dataSourceKey '${values.dataSourceKey}' unregistered. Available: ${keys.join(', ')}. Is the app fully started?`, { cause: e });
  }
  throw e;
}

When it happens

Trigger: Calling fields:apply / applyExternalFieldDefinition with values.dataSourceKey (or defaults.dataSourceKey) that is absent from dataSourceManager.dataSources — e.g. 'mysql2' when only 'main' is registered, or a key used before its data source finishes loading/registering at app init.

Common situations: Server-side scripts running during app bootstrap before external sources register; typo'd keys in migration/import scripts; data source deleted or its driver plugin disabled while automation still targets it; environment-specific keys (prod vs staging) hardcoded.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• dataSource ${dataSourceKey} not found
• Scope key "${options.scopeKey}" not found in data source "${
• dataSource ${dataSourceKey} is ${dataSourceStatus}
• dataSourcesCollections.fields:apply requires dataSourceKey
• dataSourcesCollections.fields:apply requires collectionName

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