nocobase/nocobase · error · FlowSurfaceBadRequestError

flowSurfaces addAction only supports registered action types

Error message

flowSurfaces addAction only supports registered action types/uses

What it means

This is the fallback guard of resolveSupportedActionCatalogItem: after trying the `use` branch and the `type` branch, if neither produced a catalog item (both input.type and input.use were empty/blank, or lookups matched nothing outside the earlier checks), the resolver rejects the request because only registered action types/uses are supported by flowSurfaces addAction.

Source

Thrown at packages/plugins/@nocobase/plugin-flow-engine/src/server/flow-surfaces/catalog.ts:4240

        requestedType,
      });
    }
    if (matchedAll.length && !matched.length) {
      throwUnavailableCatalogItem(matchedAll[0], {
        context: options.context || 'addAction',
        requestedType,
      });
    }
    if (matched.length > 1 && !input.containerUse) {
      throw new FlowSurfaceBadRequestError(
        `flowSurfaces addAction type '${requestedType}' requires containerUse to resolve a public action capability`,
      );
    }
    item = matched[0];
  }

  if (!item) {
    throw new FlowSurfaceBadRequestError(`flowSurfaces addAction only supports registered action types/uses`);
  }
  if (!isCatalogItemAvailable(item, options.enabledPackages)) {
    throwUnavailableCatalogItem(item, {
      context: options.context || 'addAction',
      requestedType: input.type,
      requestedUse: input.use,
    });
  }
  if (requestedType) {
    const publicKey = toPublicActionCatalogItem(item).key;
    if (requestedType !== publicKey) {
      throw new FlowSurfaceBadRequestError(
        `flowSurfaces addAction only supports public action type '${publicKey}' under '${
          input.containerUse || 'unknown'
        }'`,
      );
    }
  }

View on GitHub (pinned to fa42722fef)

Solutions

1. Ensure the request includes a valid `type` (public action key) or `use` registered in the action catalog
2. List the action catalog (e.g. via the flowSurfaces catalog endpoints) to confirm the exact key/use spelling
3. Register the custom action in ACTION_CATALOG if it is a new capability
4. Fix the client payload so the action selector value is actually submitted

Example fix

// before
await flowSurfaces.addAction({ containerUse: 'table' }); // no type/use -> throws
// after
await flowSurfaces.addAction({ type: 'customize:popup', containerUse: 'table' });

const type = String(input.type || '').trim();
const use = String(input.use || '').trim();
if (!type && !use) throw new Error('addAction requires a registered action type or use');
if (type && !ACTION_CATALOG_BY_KEY.has(type) && !(ACTION_CATALOG_BY_USE.get(use) || []).length) {
  throw new Error(`Action '${type || use}' is not registered`);
}

function isRegisteredAction(input) {
  const t = String(input?.type || '').trim();
  const u = String(input?.use || '').trim();
  return Boolean((t && ACTION_CATALOG_BY_KEY.has(t)) || (u && (ACTION_CATALOG_BY_USE.get(u) || []).length));
}

try {
  await flowSurfaces.addAction(input);
} catch (e) {
  if (e instanceof FlowSurfaceBadRequestError && /only supports registered action types\/uses/.test(e.message)) {
    // surface catalog choices to the user instead of submitting
  } else throw e;
}

When it happens

Trigger: flowSurfaces addAction called with neither type nor use (or only whitespace), or with values absent from ACTION_CATALOG_BY_KEY / ACTION_CATALOG_BY_USE such that `item` stays undefined.

Common situations: Client sends an empty payload due to a form that did not bind the action selector; typo'd or custom action key that was never registered; plugin providing the action is not registered in the catalog at all (distinct from being disabled, which throws a different 'unavailable' error).

Related errors

• flowSurfaces addBlock does not support creating '${item.key}
• flowSurfaces addAction does not support creating '${item.key
• Invalid scopeId: ${scopeId}
• `resources` must be a non-empty array
• Invalid attachment

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