Skip to main content

Troubleshooting and FAQ

The app is invisible after installation​

A running Python process reads new .pth files only at interpreter start. Recreate backend, scheduler, and workers from the same new image, then check every runtime:

bench --site SITE_NAME clear-cache
bench --site SITE_NAME migrate
bench --site SITE_NAME list-apps
python apps/insurance_broker_core/scripts/verify_bench_app_registry.py \
  --check --bench . --runtime-id "$HOSTNAME"

With a shared sites/ volume, apps.txt and the app code can differ per container. A backend PASS proves nothing for the scheduler or the workers. Never remove another owner's entry or resource without ownership evidence.

Installation failed with IBC-INSTALL-MODULES-001​

Run clear-cache, migrate, and install-app again, in this order. Do not edit installed_apps, apps.txt, or database tables by hand. See Installation.

Activation remains red​

Run the readiness check and resolve every finding code. Do not bypass the gate and do not edit activation_state directly. Typical codes are IBC-ACT-REQ-001 (a missing attestation field) and IBC-ACT-ACC-001 (an accounting strategy that is not admitted). See First steps and activation.

Mandate activation fails with IBC-MANDATE-SCOPE-EXPLICIT-001​

The mandate scope uses the all flag set to true. That scope is for display and import only. Activation needs an explicit include list of servicing-eligible product classes. See Core domains.

A distribution decision is rejected with IBC-REG-CONTEXT-001​

The regulatory context for the mandate is missing or incomplete (distribution country, customer country, risk countries, country-profile version, obligation-profile version). Complete it and document the legal review first.

Import errors​

Inspect Import Batch, Quarantine, Data Quality Issue, and Mapping Profile. Unknown schema versions deliberately get no best-effort mapping. A row error quarantines only that row; a batch contract error aborts the whole batch.

Background jobs are missing​

Check scheduler and worker restarts, Redis connectivity, outbox deliveries, and the dead-letter queue. A concurrent image recreation or a resource shortage is an infrastructure event; repeat the check on a stable runtime before you treat it as a product regression.

The sidebar looks old after an upgrade​

Run bench --site SITE_NAME migrate and reload the Desk page once. The after_migrate hook merges newly shipped workspace blocks into the existing site.

Uninstall is blocked​

The uninstall guard raises the first open criterion, for example IBC-UNINSTALL-001 for an active company. Close it and run the command again to see the next one. See Operations.

FAQ​

Do I need Helpifyr? No. The app installs, activates, and operates without any Helpifyr component. See Optional Helpifyr integration.

Is this an ERPNext fork? No. It is a normal Frappe app with no core-file overrides. ERPNext stays authoritative for its own objects.

Can I claim that a product class is supported? Only if its capability is validated for the exact product class, country, process, and release. See the overview.

Does the app post to accounting by itself? No. The default accounting strategy is None, and no function submits invoices, executes payments, or processes client money automatically.

Does it come with a GDPR, FINMA, or BaFin certification? No. It supports the workflows but is not a certification. See Security and privacy.

Which languages does the Desk support? English is the source language. A German translation covers the core cockpit, navigation, validation messages, and the supported broker DocTypes. French and Italian are not complete release languages.

Where do I get the app? From the source repository. The app is not listed on the Frappe Marketplace: the repository holds prepared listing material only, and no external publish action has been performed. See the release notes.

Where do I report bugs or security issues? Reproducible bugs and contract changes go to the issue tracker of the source repository. Security-sensitive reports go privately to the address on the Security and privacy page.