85 lines
4.3 KiB
Plaintext
85 lines
4.3 KiB
Plaintext
# Correct Custom Widget problems
|
|
|
|
## Correct an unavailable widget
|
|
|
|
The definition does not exist. If it was deleted, remove the unavailable tile from the board.
|
|
|
|
If the Custom Widgets page shows the definition with a **Migration required** badge, an administrator can open its
|
|
action menu and select **Copy migration prompt**. Give that redacted prompt to an LLM, then import the resulting v2 JSON
|
|
from the same menu. The LLM returns one complete JSON block; copy it once and select **Paste migrated widget**. Homarr
|
|
places its `template` value into the JSX editor automatically. Because arbitrary v1 display text or JSX may contain
|
|
credentials, the prompt omits that display configuration; describe the old widget's visible layout and behavior without
|
|
including secrets. Other viewers see **Contact an administrator** instead of a migration link.
|
|
|
|
Homarr keeps the v1 definition and encrypted secret after migration. The validated v2 replacement uses the same ID and
|
|
takes precedence; the archived v1 record reappears if the v2 replacement is deleted. There is no v1 permanent-delete
|
|
action during the v2 stabilization period.
|
|
|
|
Otherwise, install or create a Custom JSX v2 definition.
|
|
|
|
## Correct an invalid saved definition
|
|
|
|
The Custom Widgets page isolates a definition that does not conform to the current schema. The other definitions remain available.
|
|
|
|
An invalid definition shows its validation errors. You can delete it.
|
|
|
|
You cannot edit, enable, export, duplicate, publish, or select an invalid v2 definition. Recreate the definition or import a valid definition. Preserved v1 definitions use the separate **Migration required** workflow described above.
|
|
|
|
## Correct validation errors
|
|
|
|
Read the first schema or JSX diagnostic. Use its path to find the invalid value.
|
|
|
|
Make sure keyed API source and request names are valid and unique.
|
|
|
|
Make sure that each named request references an API source. Use explicit `$option` and `$param` references.
|
|
|
|
Make sure every option default matches its control. Use the correct request kind for each runtime component.
|
|
|
|
An incomplete API source URL or icon URL causes a form validation error. The workbench keeps the draft open.
|
|
|
|
The workbench marks the invalid field while you type. An invalid URL does not replace the form with the error boundary.
|
|
|
|
An invalid definition disables widget preview and Save/Create. The Data, Options, Actions, and Diagnostics tabs remain available so you can correct it.
|
|
|
|
The Diagnostics tab shows current schema and JSX errors, accessibility checks, and (after a preview) the redacted request
|
|
journal. It does not expose credentials or raw secret values.
|
|
|
|
## Workshop unavailable
|
|
|
|
If Workshop is unavailable, check `WORKSHOP_API_URL` and PocketBase health. Widgets that are already installed continue
|
|
to work.
|
|
|
|
## Correct request errors
|
|
|
|
Check the API source network scope. Check the base URL and credentials.
|
|
|
|
Check the request method, path, body, direct value bindings, and board permission.
|
|
|
|
For “invalid placeholder,” use `{option:name}` or `{param:name}`. Load queries can only reference options. The preview journal does not show credentials.
|
|
|
|
The journal shows the method, request ID, path template, status, and duration.
|
|
|
|
In a multi-instance deployment, all Homarr replicas must share Redis. Versioned cache invalidation is distributed
|
|
through Redis; replicas connected to different Redis databases can serve stale query responses after an action.
|
|
|
|
## Correct a Mantine prop warning
|
|
|
|
`UNKNOWN_MANTINE_PROP` is a warning. Homarr passes the prop to Mantine.
|
|
|
|
Check the prop in the documentation for the installed Mantine version. `BLOCKED_CAPABILITY` identifies an unsafe capability.
|
|
|
|
Use safe widget options, temporary inputs, or named requests instead.
|
|
|
|
## Repair an existing item
|
|
|
|
The widget option definitions changed and the saved values are invalid. Open the item settings.
|
|
|
|
Correct the marked configuration values. Homarr does not infer widget option migrations.
|
|
|
|
## Roll back safely
|
|
|
|
Before an application upgrade, back up the database and preserve the exact `SECRET_ENCRYPTION_KEY`. The v2 schema keeps
|
|
the physical v1 definition and secret tables readable by a v1 binary. Roll back the application without running
|
|
manual cleanup, verify legacy widgets, and restore the database backup if the migration itself must be reversed.
|
|
PocketBase Workshop data is a separate backup and restore operation.
|