nocobase/nocobase · error

field options invalid

Error message

field options invalid

What it means

createFieldIfNotExists, invoked from the afterCreate hook for foreign key fields, requires both collectionName and name in the field values to locate or create the backing field record. If either is missing the hook cannot proceed and throws this generic validation error.

Source

Thrown at packages/plugins/@nocobase/plugin-data-source-main/src/server/hooks/afterCreateForForeignKeyField.ts:84

    }

    if (type === 'uuid') {
      data['interface'] = 'uuid';
      data['uiSchema'] = {
        type: 'string',
        title: name,
        'x-component': 'Input',
        'x-read-pretty': true,
      };
    }

    return data;
  }

  async function createFieldIfNotExists({ values, transaction, interfaceType = null }) {
    const { collectionName, name } = values;
    if (!collectionName || !name) {
      throw new Error(`field options invalid`);
    }
    const r = db.getRepository('fields');
    const instance: FieldModel = await r.findOne({
      filter: {
        collectionName,
        name,
      },
      transaction,
    });

    if (instance) {
      if (instance.type !== values.type) {
        throw new Error(`fk type invalid`);
      }
      instance.set('sort', 1);
      instance.set('isForeignKey', true);
      await instance.save({ transaction });
      await instance.load({ transaction });

View on GitHub (pinned to fa42722fef)

Solutions

1. Include both collectionName and name in the field values payload
2. Validate the payload before calling fields:create
3. Use the standard collection-manager API for creating association fields, which fills these automatically

Example fix

// before
await db.getRepository('fields').create({ values: { type: 'bigint', interface: 'm2o' } });
// after
await db.getRepository('fields').create({ values: { collectionName: 'orders', name: 'customerId', type: 'bigint', interface: 'm2o' } });

function validateFieldValues(values) {
  if (!values?.collectionName || !values?.name) {
    throw new Error('field values require collectionName and name');
  }
}

function isCompleteFieldValues(v) {
  return typeof v === 'object' && v !== null && typeof (v as { collectionName?: unknown }).collectionName === 'string' && typeof (v as { name?: unknown }).name === 'string';
}

try {
  await fieldsRepo.create({ values });
} catch (e) {
  if (e.message === 'field options invalid') {
    console.error('Field payload missing collectionName or name:', values);
  } else throw e;
}

When it happens

Trigger: fields:create (or association field creation) invoked with values lacking collectionName or name — typically a malformed API payload or programmatic field creation.

Common situations: Custom scripts calling the fields repository without full values; API clients omitting required keys; broken integrations submitting partial field definitions.

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

• add field ${model.get('name')} failed, collection ${collecti
• fk type invalid
• foreignKey and otherKey can not be the same
• Field name already exists
• cant update field without a reverseField key

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