Unsupported --unset field "${field}". Supported fields: ${Ar

Error message

Unsupported --unset field "${field}". Supported fields: ${Array.from(UNSETTABLE_FIELDS).sort().join(', ')}.

What it means

`nb env update --unset <field>` only accepts a fixed set of unsettable fields (UNSETTABLE_FIELDS: special fields like api-base-url/auth-type/access-token/username plus all string and boolean config flags). normalizeUnsetFields rejects anything else with this error, listing the supported fields sorted. Comma-separated values are split and each element is checked individually.

Source

Thrown at packages/core/cli/src/commands/env/update.ts:196

  for (const field of UPDATE_BOOLEAN_FLAGS) {
    if (flags[field] !== undefined) {
      fields.add(field);
    }
  }

  return fields;
}

function normalizeUnsetFields(unset: string[] | undefined): string[] {
  const normalized = (unset ?? [])
    .flatMap((value) => value.split(','))
    .map((value) => value.trim())
    .filter(Boolean);

  for (const field of normalized) {
    if (!UNSETTABLE_FIELDS.has(field)) {
      throw new Error(
        `Unsupported --unset field "${field}". Supported fields: ${Array.from(UNSETTABLE_FIELDS).sort().join(', ')}.`,
      );
    }
  }

  return Array.from(new Set(normalized));
}

function buildCurrentConfigInput(
  env: NonNullable<Awaited<ReturnType<typeof getEnv>>>,
): StoredEnvConfigInput & Record<string, unknown> {
  return {
    ...env.config,
    apiBaseUrl: env.apiBaseUrl,
    authType: env.authType,
    authUsername: env.config.authUsername,
    accessToken: env.auth?.type === 'token' ? env.auth.accessToken : undefined,
  };

View on GitHub (pinned to fa42722fef)

Solutions

Copy field names exactly from the error's `Supported fields:` list (or `nb env update --help`)
If you used a comma list, check each item individually — one bad item rejects the whole call
Upgrade the CLI if the field you need is missing (`npm i -g @nocobase/cli`) — older versions have a smaller UNSETTABLE_FIELDS set
To change rather than clear a field, pass `--<field> <value>` instead of --unset

Example fix

// before
nb env update --env prod --unset dbhosst
// error: Unsupported --unset field "dbhosst"
// after
nb env update --env prod --unset db-host

Defensive patterns

Strategy: validation

Validate before calling

// Pre-validate --unset fields against the documented set:
const UNSETTABLE = new Set(['api-base-url','auth-type','access-token','username','source','download-version','docker-registry','docker-platform','git-url','npm-registry','app-path','app-root-path','storage-path','app-public-path','cdn-base-url','env-file','app-port','app-key','timezone','db-dialect','builtin-db-image','db-host','db-port','db-database','db-user','db-password','db-schema','db-table-prefix','builtin-db','dev-dependencies','build','build-dts','db-underscored']);
fields.forEach(f => { if (!UNSETTABLE.has(f)) throw new Error(`bad --unset field: ${f}`); });

Try / catch

try {
  await nb(['env','update','--env',env,'--unset',fields.join(',')]);
} catch (err) {
  if (/Unsupported --unset field/.test(err.message)) {
    console.error('Valid fields are listed in the error; fix and retry.');
  }
  throw err;
}

Prevention

Copy field names from the CLI help or the error's Supported fields list, never from memory
When unsetting multiple fields, test each name individually first
After CLI upgrades, re-check that the fields you script still exist
Use --unset for clearing values and --<field> <value> for changing them

When it happens

Trigger: Running `nb env update --env <env> --unset <field>` where field (or any item in a comma-separated list) is not in UNSETTABLE_FIELDS — e.g. `--unset db-password,typo-field`, deprecated flag names, or fields that never existed.

Common situations: Typos in field names (`--unset dbhosst`); trying to unset a field added in a newer CLI than the one installed (or removed in an upgrade); passing spaces or wrong casing; assuming read-only fields like env name can be unset.

Related errors

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