Schema Deploy Errors

flexkit deploy compares your local schema with the deployed schema before applying an update. Compatibility checks prevent changes that could make existing data unreadable or unexpectedly remove fields used by Studio and GraphQL clients.

Types of Changes

Schema changes fall into three groups:

Safe changes, such as adding an entity or attribute, deploy normally.
Intentional breaking changes, such as removing an entity or attribute, are blocked until you acknowledge them with --allow-breaking-changes.
Unsafe changes, such as changing an existing attribute’s dataType, cannot be overridden. Migrate the data through a new attribute instead.

The --allow-breaking-changes option only acknowledges entity and attribute removals. It does not bypass invalid schema configuration, generated SDL errors, or unsafe data type changes.

Configuration errors

Some deploys stop before the compatibility check because the configuration itself is invalid. The CLI prints the path of the offending value; fix the config and run flexkit deploy again.

Invalid validation fragment at schema[i].attributes[j].validation (422). The attribute’s Zod validation compiled to a JSON Schema fragment the backend cannot compile, or the fragment exceeds the 16 KB limit. The CLI rejects unsupported rules such as .refine() locally first; this error usually means an outdated CLI or a hand-edited payload. See Validation.
Undeclared menu group at schema[i].menu.group. The entity’s menu.group names a group that is not listed in the project’s menuGroups. Add { name, title } to menuGroups or remove menu.group. Duplicate menuGroups[].name entries are rejected at menuGroups[i].name.
Legacy config file. A flexkit.config.tsx is refused before anything is sent: rename it to flexkit.config.ts, replace icon components with lucide icon names, use booleans for hidden and readOnly, and remove extensions, basePath and commands.

Error Guides

Follow the guide linked by the CLI error before retrying the deployment.