Flowmaker SDK [beta]Docs
search
GitHub

Troubleshooting and Known Gotchas

This page covers common integration issues seen when wiring FlowBox UI components.

[NOTE!lightbulb/DEBUG STRATEGY] Start by validating jsonEnv('datacatalog') and currently effective filters before debugging component internals.

1) No source connections loaded

Symptoms

  • DCSourceConnection stays empty.

Checks

  • dcapiurl is non-empty.
  • sourcetypefilter is not null.
  • DataCatalog endpoint is reachable.

Why

DCSourceConnection load condition requires both URL and non-null filter.

[WARNING!report/ENTRYPOINT CONDITION] sourcetypefilter = null silently blocks loading even when URL is valid.

2) Catalog entry not restored on load

Symptoms

  • Persisted ID exists, dropdown appears unselected.

Checks

  • initialselection matches an item in current filtered set.
  • Source-type/data-type/name filters are not excluding the entry.

Why

Selection is applied against currently loaded/filtered entries.

[NOTE!lightbulb/FILTER ORDER] API-side namefilter + client-side filters can combine and hide a valid persisted ID.

3) Picker shows "Too many entries"

Symptoms

  • No rows shown until search text is entered.

Why

Picker switched to server-search mode (>100 initial items).

Action

  • Type a search query.
  • Keep sourceConnectionId scoped to reduce result size.

[WARNING!monitoring/SCALING BEHAVIOR] This is expected behavior, not a rendering bug.

4) Removed item still appears selected upstream

Symptoms

  • UI and persisted values diverge.

Action

  • In onRemove, update both local selectedIds and $values.
  • Recompute and emit validity in same handler.

[WARNING!schedule/CONFIG INTEGRITY] If local state and $values are updated in different paths, saved config can contain removed IDs.

5) Column key not rendering

Symptoms

  • Requested picker column does not appear.

Checks

  • Key exists in COLUMN_DEFS, or follows supported dynamic prefixes:
    • sourceParams.*
    • metadata.*

Note

sourceType is not provided by default helper resolution.

[NOTE!lightbulb/SURPRISING BEHAVIOR] Unknown column keys are ignored silently; this often looks like "random missing columns".

6) Unexpected cross-form column behavior

Symptoms

  • Column formatting changed after importing another form.

Why

COLUMN_DEFS is shared mutable runtime map.

Action

  • Centralize column-definition overrides in one place.
  • Avoid conflicting overrides for same key.

[WARNING!public/GLOBAL STATE HAZARD] Global column overrides are order-dependent; the last override wins for the whole runtime.

7) Validity never updates

Symptoms

  • Save/apply allowed when required selection is missing.

Action

  • Update $validity in selection/source handlers.
  • Emit emit('validity', $validity) after state change.
  • Prefer change-detection guards to avoid excessive emits.

[WARNING!rule/VALIDATION OWNERSHIP] If a handler updates $values but not $validity, the host can accept invalid configs.

8) DataCatalog config missing from environment

Symptoms

  • jsonEnv('datacatalog') resolves null.

Action

  • Ensure context.environmentVars['environment/datacatalog'] exists and contains valid JSON.
  • Confirm JSON includes expected url key.

[NOTE!lightbulb/ENV CONTRACT] The bridge parser returns null on parse failure; malformed JSON and missing key look identical unless logged.

Reference

  • sdk/config/flowbox-ui/src/bridge.ts
  • sdk/config/flowbox-ui-components/src/DCSourceConnection.svelte
  • sdk/config/flowbox-ui-components/src/DCCatalogEntry.svelte
  • sdk/config/flowbox-ui-components/src/DCCatalogEntryPicker/DCCatalogEntryPicker.svelte