Error Codes

Every error in the CRUD bundle has a structured code:

CRUD-{DOMAIN}-{ACTION}-{REASON}

• Domain — area of the app: LISTING, FORM, DETAIL, IMPORT, MODAL, SIDEBOX
• Action — what was attempted: FETCH, DELETE, SAVE, RESET, SELECT, EXPORT, DUPLICATE
• Reason — why it failed: FAILED, EMPTY, LIMIT, NOT_FOUND, INVALID

Each error also has a 4-digit internal code for quick identification in logs and support tickets. Codes are grouped by domain:

Setup

1. Register the error catalog API route

import { crudErrorCatalogHandler } from
  "@phpcreation/frontend-crud-react-nextjs-bundle/utils/errors";
 
export const GET = crudErrorCatalogHandler;

Exposes GET /api/error-catalog — used by resolveError() to fetch CRUD error metadata at runtime.

2. Show inline error details with AppErrorRenderer

import { AppErrorRenderer } from
  "@phpcreation/frontend-crud-react-nextjs-bundle/components";
 
<AppErrorRenderer error="CRUD-FORM-SAVE-FAILED" />

Requires step 1 so resolveError() can reach /api/error-catalog.

3. Link toasts to this page

Set NEXT_PUBLIC_DOCS_BASE_URL to have error toasts include a “Read docs →” link:

NEXT_PUBLIC_DOCS_BASE_URL=https://dev.react-doc.phpr.link

When not set, toasts show the error message only — no link is generated.

4. Sentry tag filtering

Every showCrudError(code, message, originalError) call that receives an originalError argument tags Sentry:

scope.setTag("crud_error_code", "CRUD-LISTING-DELETE-FAILED");
scope.setContext("crud_error", {
  code: "CRUD-LISTING-DELETE-FAILED",
  message: "...",
  domain: "listing",
});

Filter in Sentry:

crud_error_code:CRUD-FORM-SAVE-FAILED

User-interaction errors (e.g. “no items selected”) do not send to Sentry — only errors with a real originalError.

Listing Errors

CRUD-LISTING-FETCH-FAILED

Message: Failed to load listing data

When it occurs: The server action that fetches the resource collection returned an error. Triggered when getItemAction throws inside ListingContext.

Resolution:

• Reload the page to retry
• Verify the tenant and API configuration
• Confirm the user session is still valid

CRUD-LISTING-DELETE-FAILED

Message: Failed to delete the item

When it occurs: deleteItemAction returned an error for a single-item delete.

Resolution:

• Verify the user has DELETE permission on this resource
• Check if the item is referenced by other entities (foreign key constraint)
• Inspect the API response for a specific message

CRUD-LISTING-BULK-DELETE-EMPTY

Message: No items selected to delete

When it occurs: Bulk delete triggered with zero items checked.

Resolution: Select at least one row using the checkboxes before triggering bulk delete.

CRUD-LISTING-BULK-DELETE-LIMIT

Message: You can only delete up to 20 items at a time

When it occurs: More than 20 items selected when bulk delete is triggered.

Resolution: Deselect items until 20 or fewer are checked, then retry in batches.

CRUD-LISTING-BULK-DISABLE-EMPTY

Message: No items selected to disable

When it occurs: Bulk disable triggered with zero items checked.

Resolution: Select at least one row before triggering bulk disable.

CRUD-LISTING-BULK-DISABLE-LIMIT

Message: You can only disable up to 20 items at a time

When it occurs: More than 20 items selected when bulk disable is triggered.

Resolution: Reduce selection to 20 or fewer items, then retry in batches.

CRUD-LISTING-BULK-EDIT-FAILED

Message: Failed to edit one or more items

When it occurs: updateItemAction returned an error during a bulk edit operation.

Resolution:

• Reload the listing and verify which items were updated
• Check the user’s edit permissions on the affected resource
• Inspect the API error for validation details

CRUD-LISTING-SELECTION-LIMIT

Message: You can only select up to 20 items

When it occurs: Trying to check a 21st item in the listing table.

Resolution: Deselect some items before adding new ones to the selection.

CRUD-LISTING-KVS-FIELDS-SAVE-FAILED

Message: Failed to save listing fields preference

When it occurs: The KVS API call that persists the user’s visible-columns configuration failed.

Resolution:

• Verify NEXT_PUBLIC_KVS_API_RESOURCE_NAME and NEXT_PUBLIC_KVS_DATA_STORE_TOGGLE are set
• Check the user has write permissions on the KVS endpoint

CRUD-LISTING-KVS-INTERFACE-SAVE-FAILED

Message: Failed to save listing interface preference

When it occurs: The KVS API call that persists the full listing interface (columns, actions, pagination) failed.

Resolution: Same as CRUD-LISTING-KVS-FIELDS-SAVE-FAILED above.

CRUD-LISTING-KVS-INTERFACE-RESET-FAILED

Message: Failed to reset listing interface

When it occurs: The KVS delete request for the saved interface entry returned an error.

Resolution:

• Check the user has delete permissions on the KVS endpoint
• Refresh and retry the reset

CRUD-LISTING-KVS-INTERFACE-RESET-EMPTY

Message: No saved interface found to reset

When it occurs: Reset triggered but no KVS entry exists for this listing’s interface.

Resolution: Save the interface at least once using Save interface before attempting a reset.

CRUD-LISTING-DUPLICATE-FAILED

Message: Failed to duplicate item

When it occurs: handleListingDuplicate in useActionButtons threw an error when calling getItemAction on the duplicate endpoint.

Resolution:

• Verify the user has CREATE permission on this resource
• Check the API response for the root cause

CRUD-LISTING-INLINE-SAVE-FAILED

Message: Failed to save inline edit

When it occurs: An inline cell edit was rejected by the API or an unexpected exception occurred during the update.

Resolution:

• Verify the entered value is valid for this field type
• Use the full edit form if the problem persists
• Check the browser console for more detail

CRUD-LISTING-MASS-UPDATE-FAILED

Message: Mass update failed

When it occurs: The updateItemAction call inside the mass update handler returned an error or threw an exception.

Resolution:

• Reload the listing and verify which items were updated
• Check the user’s edit permissions on the affected resource

CRUD-LISTING-EXPORT-NO-DATA

Message: No data to export

When it occurs: Export triggered but the listing has no loaded data.

Resolution:

• Wait for the listing to finish loading
• Remove filters that may be returning zero results

CRUD-LISTING-FILTERS-SAVE-FAILED

Message: Failed to save filter configuration

When it occurs: The KVS API call that persists the active filter configuration failed in DefaultFiltersMenu.

Resolution:

• Verify NEXT_PUBLIC_KVS_API_RESOURCE_NAME and NEXT_PUBLIC_KVS_DATA_STORE_TOGGLE are set
• Check the user has write permissions on the KVS endpoint

CRUD-LISTING-KANBAN-UPDATE-FAILED

Message: Failed to update item status

When it occurs: Moving a Kanban card to a new column triggered an updateItemAction that returned an error. The board refreshes to the last known state.

Resolution:

• Verify you have edit permission on this item
• Check the API response for validation details

CRUD-LISTING-ANCHOR-NOT-FOUND

Message: Anchor item not found in current page

When it occurs: The URL contains an anchor query parameter with an item ID not present in the current page results — item deleted, filtered out, or on a different page.

Resolution:

• Remove the anchor parameter from the URL
• Check if the item was deleted or hidden by the current filters

CRUD-LISTING-ORDER-UPDATE-FAILED

Message: Failed to update item order

When it occurs: The updateItemAction call to update priority or lft/rgt tree positions returned an error.

Resolution:

• Reload the listing to get the current server order
• Verify the resource supports ordering (sortable: true in column config)
• Check the API response for the root cause

Detail-Show Errors

CRUD-DETAIL-DELETE-FAILED

Message: Failed to delete item

When it occurs: handleDelete in useActionButtons threw an error when calling deleteItemAction from the detail/show page.

Resolution:

• Verify the user has DELETE permission on this resource
• Check if the item is referenced by other entities (foreign key constraint)
• Inspect the API response for a specific message

CRUD-DETAIL-DUPLICATE-FAILED

Message: Failed to duplicate item

When it occurs: handleDuplicate in useActionButtons threw an error on the detail page.

Resolution:

• Verify the user has CREATE permission on this resource
• Check the browser console and API response for details

CRUD-DETAIL-EXPORT-NO-DATA

Message: No data to export

When it occurs: Export triggered before the detail page item data finished loading.

Resolution: Wait for the detail page to fully load, then retry.

CRUD-DETAIL-EXPORT-NO-FIELDS

Message: No fields configuration for export

When it occurs: Structured export (CSV/Excel) triggered but no fields prop passed to ShowHeaderActions.

Resolution: Pass a fields array to ShowHeaderActions. Alternatively, use the raw JSON export which does not require field definitions.

CRUD-DETAIL-EXPORT-FAILED

Message: Failed to export data

When it occurs: An unexpected error occurred while generating the export file in handleExport.

Resolution:

• Try the raw JSON export option
• Check the browser console for error details

Form Errors

CRUD-FORM-SAVE-FAILED

Message: Failed to save

When it occurs: res.error returned by createItemAction or updateItemAction in EditEntityForm, AddEntityForm, QuickEdit, or QuickAddModal.

Resolution:

• Read the appended server message in the toast — it usually contains the specific field validation error
• Correct the highlighted fields and resubmit
• Confirm all required fields are filled

CRUD-FORM-EXCEPTION

Message: An error occurred

When it occurs: An unhandled JavaScript exception thrown inside the form save handler (catch block in EditEntityForm or AddEntityForm).

Resolution:

• Open the browser console — the full stack trace is logged there
• This is distinct from an API validation error; check for null references or missing data

CRUD-FORM-TRANSLATIONS-FETCH-FAILED

Message: Failed to load translation data

When it occurs: The translations API call in getTranslatableData returned an error. Only triggered when the form is configured as translatable: true.

Resolution:

• Reload the page to retry fetching translations
• Verify the translations API endpoint is accessible
• The form can still be submitted without pre-existing translations loading

Import Errors

CRUD-IMPORT-FILE-INVALID

Message: Please upload a CSV file

When it occurs: A non-CSV file selected or dropped into the import modal.

Resolution: Export your data as .csv from the source system and re-upload.

CRUD-IMPORT-FILE-READ-FAILED

Message: Error reading file

When it occurs: The browser’s FileReader API triggered onerror — the file could not be read.

Resolution:

• Ensure the file is not open or locked in another application
• Try saving it to a different location and uploading again
• Open the file in a text editor to verify it is not corrupt

CRUD-IMPORT-CSV-PARSE-FAILED

Message: Error parsing CSV file

When it occurs: The CSV parsing logic threw an exception — the file content could not be decoded with the configured delimiters.

Resolution:

• Verify the field delimiter and text delimiter match those used in the CSV
• Open the file in a text editor to check its raw structure
• Re-export using standard settings (comma-delimited, double-quote text)

CRUD-IMPORT-JOB-FAILED

Message: Failed to import data

When it occurs: The server returned an error while creating or executing the import job in EditListingImportModal.

Resolution:

• Verify the CSV matches the expected column structure for this resource
• Check user permissions for import operations
• Inspect the API response for validation details

Modal Errors

CRUD-MODAL-KVS-SAVE-FAILED

Message: Failed to save default form values

When it occurs: The KVS API call that saves the default form field values in DefaultFlagModal returned an error.

Resolution:

• Verify NEXT_PUBLIC_KVS_API_RESOURCE_NAME is set
• Check the user has write permissions on the KVS endpoint

CRUD-MODAL-KVS-RESET-FAILED

Message: Failed to reset default form values

When it occurs: The KVS delete request for the saved defaults entry failed in DefaultFlagModal.

Resolution:

• Check the user has delete permissions on the KVS endpoint
• Refresh and retry the reset

CRUD-MODAL-DUPLICATE-FAILED

Message: Failed to duplicate item

When it occurs: Either the initial fetch (getItemAction) or the save (createItemAction) in QuickDuplicateModal returned an error.

Resolution:

• Verify the user has CREATE permission on this resource
• Check the API response for validation details

CRUD-MODAL-FILTER-SAVE-FAILED

Message: Failed to save filter

When it occurs: An error thrown while saving a new filter configuration in AddFilterModal.

Resolution:

• Verify the filter configuration is valid
• Check the browser console for more detail

Sidebox Errors

CRUD-SIDEBOX-NO-FORM-INPUTS

Message: No form inputs defined for this resource

When it occurs: The sidebox attempted to open a Quick Add modal but formInputsAdd was not configured. The user is redirected to the standard add page as a fallback.

Resolution:

• Pass formInputsAdd to the Sidebox component for this resource to enable quick-add
• If the redirect to the standard add page is acceptable, this toast can be ignored

UI Display Levels

Each error specifies a ui.level that controls how it renders:

All current CRUD bundle errors use toast.

Adding New Error Codes

// 1. Add the entry to the catalog
"CRUD-MYFEATURE-ACTION-FAILED": {
  code: "CRUD-MYFEATURE-ACTION-FAILED",
  internalCode: 7001, // next available in your domain range
  httpStatus: 500,
  domain: "crud-v2",
  ui: {
    level: "toast",
    message: "Human-readable message shown in the toast",
    action: "What the user should do",
  },
  docs: {
    slug: "CRUD-MYFEATURE-ACTION-FAILED",
    message: "Same or expanded message for the docs page",
    description: "Detailed explanation of root cause.",
    actions: [
      { label: "Step 1 to resolve" },
      { label: "Step 2 to resolve" },
    ],
  },
},

// 2. Call it — pass the original exception as 3rd arg to tag Sentry
import { showCrudError } from "@phpcreation/frontend-crud-react-nextjs-bundle/utils/errors";
 
// User-action error (no Sentry)
showCrudError("CRUD-MYFEATURE-ACTION-FAILED");
 
// Server/exception error (tags Sentry with crud_error_code)
showCrudError("CRUD-MYFEATURE-ACTION-FAILED", res.error, originalException);

// Extending the catalog in a consuming app:
import { CRUD_ERROR_CATALOG } from
  "@phpcreation/frontend-crud-react-nextjs-bundle/utils/errors";
 
const APP_ERROR_CATALOG = {
  ...CRUD_ERROR_CATALOG,
  "MYAPP-CUSTOM-ERROR": { /* ... */ },
};
 
export async function GET() {
  return Response.json(APP_ERROR_CATALOG);
}