14. Troubleshooting and Recovery Procedures
Installing the complete Windows package
Download the Win32 or Win64 application ZIP and extract the entire ZIP into its own writable folder before starting VCL2FMXConverter.exe. Win64 needs 64-bit Windows. Keep the Win32 and Win64 editions in separate folders. Do not run from inside the ZIP or copy only the executable. RAD Studio is needed to build Delphi projects, not to run the downloaded converter.
Keep this layout together: VCL2FMXConverter.exe and WebView2Loader.dll in the same folder; Localization\Languages containing all 35 JSON language packs; mapping_packs containing the 22 supplied JSON packs; docs\Help containing the complete Help tree and guides; and the supplied licenses and README.txt. These are relative paths beneath the executable folder, not folders beside the ZIP.
Localization\Languages is required for interface and report translations. Preserve the English en-US.json pack as well as the other supplied languages. A missing or unreadable selected report language pack can stop a conversion with "The selected report language pack could not be loaded." Restore the complete folder from the same release ZIP and restart the converter.
WebView2Loader.dll must be directly beside VCL2FMXConverter.exe and match the executable architecture: x86 for Win32, x64 for Win64, even when running Win32 on 64-bit Windows. Use the DLL supplied in that edition of the release ZIP. The loader supports the embedded mapping browsers; it is not the WebView2 Runtime.
Install or update Microsoft Edge WebView2 Evergreen Runtime if it is absent. Obtain it from https://developer.microsoft.com/microsoft-edge/webview2/ under Download the WebView2 Runtime. The Evergreen Bootstrapper needs Internet access; use the appropriate Evergreen Standalone Installer for an offline computer. Having the Microsoft Edge browser installed is not a substitute for the Runtime. Do not download replacement DLLs from third-party DLL sites.
The embedded browsers use Edge when available and may fall back to an older browser engine if WebView2 is unavailable. A window that opens is therefore not proof of correct WebView2 deployment. If mapping views are blank or render incorrectly, check the loader location and architecture, then the Runtime installation. Close and reopen the converter after correcting the installation.
Keep mapping_packs with the application even when mapping-pack support is not currently enabled. Missing packs remove that optional conversion coverage. Preserve docs\Help and all its subfolders; missing Help files prevent Help from opening. Help opens in your default browser. Keep the converter running while using its local Help URL; English Help is available offline, while automatic Help translation needs Internet access.
Use a writable output folder separate from both the original VCL project and the converter installation. Keep an independent backup of the original project. The signed-in Windows account also needs access to its local application-data folder for language settings and browser data. Before replacing an installation, close the converter and back up customized language or mapping packs. Extract a fresh complete release rather than mixing files from different releases.
Before the first conversion, verify that the Language selector lists the supplied languages, the mapping views display, and Help opens. Review the conversion report, then compile and test the generated project in Delphi. Successful conversion does not remove the need to review unsupported components and manual changes.
| Symptom | Likely Cause | Recommended Response |
|---|---|---|
| Form reader error | An unsupported VCL property or malformed FMX output was emitted. | Fix the converter rule, regenerate into a clean output folder, and retest. |
| Compiler errors after regeneration | A converter rule is missing or incomplete. | Treat the compiler message as the next engineering target and improve the converter globally. |
| Runtime access violation | A startup, event, media, drawing, or binding mismatch remains. | Trace the workflow, isolate the phase, and improve the converter behavior globally. |
| Visual mismatch only | The app is basically working but presentation differs. | Defer deep visual polishing until structural and runtime behavior are stable. |
| Code Insight disagreement | The IDE parser is stale or confused. | Trust the real compiler and reopen files or restart the IDE if needed. |
| Conversion completed with blocking issues | A real unsupported component or blocking rule gap was detected. | Stop there, read the report, and improve the converter globally before trusting the output. |
| External project asset reference not copied | The project shell references a file outside the source tree or in an unresolved path. | Copy or relocate the asset manually, then decide whether the generator needs a new generic asset-copy rule. |
If a run goes badly, do not try to repair everything at once. The fastest route is usually to identify the highest-severity problem, improve the converter globally, regenerate clean output, and retest.