Troubleshooting

Symptoms are grouped by where you see them. Most engine problems are visible in the browser developer console of the host page (web app or preview harness): the engine logs each message it receives and sends.

The engine does not load

Symptom	Likely cause	Fix
Blank iframe, no console output	The engine URL is wrong or the version folder was removed from the engine store	Open the questionnaire's Engine tab and check the manifest link; republish or Change Engine to an existing version
Blank iframe, engine logs "waiting"	The host never sent init, or sent it before the iframe finished loading	Send init from the iframe's load event; in the preview harness press Send to Engine
Engine loads but shows nothing	init was sent with an empty sections list, or all sections are hidden by logic	Pass the section identifiers you want, or omit sections to show everything
Preview in the designer keeps reloading	Expected: the preview refreshes shortly after every edit	Wait for edits to settle; use Current question only to shorten the path

Rendering problems

Symptom	Likely cause	Fix
A question shows its text but no answer control	The questionnaire uses a question type the engine does not include	Add the component to the engine, or rebind the questionnaire to an engine that has it
Wrong language for question text	The questionnaire has no translation for the requested language	Add the translation in the designer; the engine falls back to the default language
Wrong language for buttons and messages	The interface language sent in init is not one of the supported locales	Send a supported locale; unsupported ones fall back to English
Icons appear blank in the mobile app	The component uses an icon that is not bundled in the engine	Add the icon to the engine and republish
Layout looks different on web and mobile	The host viewport differs; engines are designed for a phone-sized viewport	Keep components responsive to width; test in the preview's phone frame and in the mobile app
Dark mode colours are off in a custom component	Manual colours without dark variants	Use the shared UI components or add dark: variants

Navigation and logic

Symptom	Likely cause	Fix
Next stays disabled	The question is required and has no valid answer, or the component reports errors	Answer the question; for custom components, check that errors is emitted empty once valid
The questionnaire jumps to an unexpected question	A jump targets a question that is not part of the current session (for example in an unselected section); the engine falls back to the next question and reports an error	Check the host's error log; adjust the logic or the section selection
Logic runs but nothing happens	An on_answer action group calls no navigation method	Expected: the engine advances automatically; add an explicit jump if you need a different target
Scrollable mode ignores jumps	Navigation methods do not apply in scrollable mode	Use conditions to hide questions; jumps are for paged mode
A variable is empty in the submission	It was never set, or set on a question the patient did not reach	Check the designer's simulation for the path; give the variable a default value

Submission

Symptom	Likely cause	Fix
submit never reaches the host	The host listens for messages on the wrong window or filters them out	Listen on the page window and check type === "submit"
Submission rejected by the API	Missing context (patient, enrollment, slot) or the slot was already answered	Check the API error; the web app shows the reason in a notice
Answers missing in the submission	Questions were skipped by logic, or the component never emitted answer	Skipped questions are expected to be absent; for custom components check the emit
Anonymous page shows "not available"	The link has a start or end date outside the current time	Generate a new link or adjust the dates

Custom engine builds

Symptom	Likely cause	Fix
Build fails while downloading the core	The core reference in the manifest is incomplete or unreachable	Copy the whole core block from the core's published manifest
Component not found at runtime	mainFile does not match the component file name	Make mainFile equal to the file name without .vue
Settings form empty in the designer	Schema.json or UISchema.json missing or invalid JSON	Validate both files; the Form preview in the editor shows the result
Publish refused	The engine builder feature is off for the instance, or the role lacks the permission	Ask an administrator to enable the feature or grant the permission
Questionnaire refuses the new engine	It uses question types the new engine does not include	Add the components or convert the questions first