IMDTouchKnowledge BaseShop main store

Troubleshooting

Fix WebIQ Designer Stuck Loading an HMI Project ZIP

HMI and touchscreens Published 7 min read

Short answer

WebIQ Designer sticks on the Loading HMI project screen because the ZIP was packed by hand: it carries an extra HMI wrapper directory and file entries stored with method 0 instead of deflate method 8. The runtime tolerates the archive; the Designer import does not. Unpack it into the projects directory without the wrapper folder, then export the HMI from Designer or Runtime Manager.

On this page
  1. What the stuck screen and the log say
  2. Why the runtime opens what the Designer rejects
  3. The two defects in the archive
  4. Inspect the ZIP before changing anything
  5. Rebuild the archive through WebIQ
  6. Test the file that actually fails
  7. The decision
  8. Questions asked

WebIQ Designer 2.18.0.307 sticks on the "Loading HMI project" screen when the project ZIP was packed by hand instead of exported by WebIQ. The archive carries an extra HMI wrapper directory above the main HMI directory, and some file entries use store compression (method 0) instead of deflate (method 8). The runtime tolerates that archive; the Designer import path does not, and its worker dies on a JSON exception while the screen waits forever. Unpack the archive into the projects directory without the wrapper folder, confirm a single webiq.json, restart the Designer session, and export the HMI from Designer or Runtime Manager. That export is the valid ZIP; do not rebuild it with a generic archiver.

What the stuck screen and the log say #

The hang and the log lines are one event. The Designer's backend worker crashed while reading the project, the interface never received a result, and the loading screen never clears. The [C | api] entries are the crash; the [I | system] entries are routine bookkeeping that continues around it.

Where you see it Message What it means
Designer screen Stuck on "Loading HMI project" Backend worker failed; the UI waits indefinitely
Designer log [I | system] Project '20356e9d-b9cc-402f-a829-3800984a76f7' has been loaded. Project registered; content not yet parsed
Designer log [C | api] Worker executor has thrown an unhandled nlohmann::json_abi_v3_11_3::detail::type_error exception The JSON library threw inside the worker and nothing caught it
Designer log what(): [json.exception.type_error.316] invalid UTF-8 byte at index 3: 0x8D Entry data reached the parser in a form it did not expect
Designer log [C | api] System stability is compromised The worker is down; restart the session rather than retrying
Designer log [I | system] Loading project 'HMI_new' as EFXJ... The log carries on after the crash; the screen does not
Designer 2.18.0 import dialog Error uploading HMI project (Error-Code: 500, Category: http, Message: Internal Server Error) The same failure surfaced as an HTTP 500
Runtime Manager 2.18.0 upload Upload failed with status 500 () A second instance rejects the same archive
Designer 2.19.0 on a PC The uploaded archive does not contain a valid WebIQ HMI project, e.g. structure should be: project folder, HMI project folder. The explicit diagnosis: the folder layout is wrong

Read the 0x8D message literally and it stops looking mysterious. The parser reached byte index 3 of a string it was decoding and found 0x8D where a leading byte must be. Work the number: 0x8D is 141 in decimal, 141 is 1000 1101 in binary, and a byte whose top two bits are 10 is a UTF-8 continuation byte, which can only follow a lead byte and can never begin a sequence. The bytes were never valid text; the worker read the entry data in a layout a WebIQ export does not produce. In the JSON library behind that message, a type_error 316 means the input string is not valid UTF-8, so the defect is in the bytes handed to the parser, not in the parser.

The [C | api] level is what separates this fault from cosmetic WebIQ behavior such as why a WebIQ button stays highlighted after touch release — that is a display question with a working project behind it, while this is a crashed worker with no result coming.

Why the runtime opens what the Designer rejects #

A project already running on the device proves nothing about the archive that produced it. The runtime serves the HMI from the files it holds; the Designer import path validates the archive layout, reads every entry, and parses the project JSON. An archive that did not come from WebIQ Designer or Runtime Manager can pass the first path and fail the second. Instances differ, too: the file in this failure ran on the owner's ctrlX CORE and still returned status 500 on a second Runtime Manager 2.18.0, so one device accepting the file validates nothing. When you need to know exactly which file the runtime is serving, that is how to find the runtime file an HMI terminal actually loads.

The two defects in the archive #

Both defects come from packing the ZIP by hand:

  1. Wrong directory structure. The archive contains an HMI directory and only then the main HMI directory below it. WebIQ expects a project folder with the HMI project folder inside it, so the tree is one wrapper level too deep at the top.
  2. Unsupported compression. Not all file entries use deflate; some use store, which WebIQ does not support, and the data is laid out differently than a WebIQ export lays it out.

Neither defect is corruption. Genuine WebIQ project corruption does occur, but it is rare and cannot be reproduced reliably enough to chase, so rule out packaging first — it explains this exact symptom set. A wrapper directory the receiving tool does not expect is a classic hand-packing failure in other tools as well; it is also what stops an H8/2600 decompile when the update image has a wrapper.

Inspect the ZIP before changing anything #

List the entries and the compression method of each before you change anything. Python's standard zipfile module reports the method as a number: 8 is deflate, 0 is store.

import sys
import zipfile

archive_path = sys.argv[1]                # illustrative: ZIP path passed as the first argument
archive = zipfile.ZipFile(archive_path)   # opens the archive for reading
for entry in archive.infolist():          # each entry is a zipfile.ZipInfo
    print(entry.compress_type, entry.filename)
Finding Verdict
The first path segment is HMI, with the main HMI directory below it Wrapper directory; omit it when unpacking
Any file entry prints 0 Store compression; unsupported, and disqualifying on its own
Every file entry prints 8 Deflate; what a WebIQ export produces
More than one webiq.json, or a second project nested inside Ambiguous project root; remove the stray copy before repacking

For a reference layout, export any healthy project from Runtime Manager and run the same listing on it, then compare the two trees top level by top level. Run the inspection on the exact file that fails, not on a copy you re-saved along the way.

Rebuild the archive through WebIQ #

  1. Stop the project on the device — this takes the operator interface off the machine, so do it with the line stopped or in a safe state, not mid-cycle.
  2. Keep the original ZIP untouched as the backup.
  3. Unpack the archive into the WebIQ projects directory of the instance you are repairing, omitting the wrapper HMI directory, so the project folder sits directly in the projects directory and contains the HMI project folder.
  4. Confirm exactly one webiq.json at the project level and no nested project.
  5. Restart the Designer session. The [C | api] line already reported compromised stability, so start from a clean worker instead of retrying the import.
  6. Export the HMI from Designer or Runtime Manager. This export is the repaired ZIP — the archive format the Designer expects.
  7. Re-run the inspection listing on the export: 8 on every file entry and the same top-level layout as your reference export.

If the original archive is all you have and nothing will open it, the last-resort path is how to recover an HMI program when the source file is lost; here the runtime copy still exists, so unpack-and-export is the direct fix.

Test the file that actually fails #

During the support exchange behind this failure, a file with a different filename and a different size loaded cleanly in Designer 2.19.0 and briefly suggested a healthy project — until the correct file was supplied and failed. Before concluding anything, record the identity of the archive that actually fails:

Get-FileHash .\HMI_new.zip -Algorithm SHA256
Get-Item .\HMI_new.zip | Select-Object Name, Length, LastWriteTime

HMI_new.zip stands in for your own file name. Run every test against that hash. A file that opens in one Designer version and a file that fails in another are two different archives until the hashes match.

The decision #

  • Confirmed wrapper directory plus store entries behind the stuck screen: stop pushing the archive through the Designer import. Unpack without the wrapper, export from Designer or Runtime Manager, and import that export — it opens.
  • You need proof before touching the running project: load the archive in Designer 2.19.0 on a PC, since 2.19.0 is not released for ctrlX, and read the structure message, or upload it to a second Runtime Manager 2.18.0 and expect the 500. Both are diagnosis only; neither repairs anything.
  • You want to test the runtime's own copy: stop the running project, download it, and upload it under a different folder name — a clean upload and start tell you the runtime holds a usable project. This costs HMI downtime and adds nothing the unpack-and-export fix does not already give you, so use it only when you doubt the runtime's files.
  • After the export: import it into Designer 2.18.0.307 on the ctrlX CORE. The project opens, the loading screen clears, and the project is maintainable in the Designer again.

Questions asked

Does the project opening in the browser mean the ZIP is valid?

No. The runtime serves the files it already holds, so a running project says nothing about the archive that produced it. The same hand-packed ZIP ran on one ctrlX CORE and returned status 500 on a second Runtime Manager 2.18.0. Only an archive exported by WebIQ Designer or Runtime Manager counts as a validated project file.

Why does the log report an invalid UTF-8 byte when the project text looks fine?

The message names the byte the parser choked on, not your project text. 0x8D is 141 in decimal, 10001101 in binary, and its top two bits, 10, mark a continuation byte that cannot begin a UTF-8 sequence. The worker read entry data in a layout a WebIQ export never produces, so a byte string that was never text reached the JSON parser.

Can I fix the ZIP by repacking it with a desktop archiver?

No. Choosing deflate in a generic archiver does not reproduce the directory layout, entry ordering and data layout WebIQ writes, and a single store entry is enough to fail the import. Unpack into the projects directory without the wrapper HMI folder and export from Designer or Runtime Manager; that export is the repaired file.

Is the project corrupted?

Almost certainly not; it is wrongly packaged. An HMI wrapper directory above the main HMI directory and store-method entries are packaging defects, and both were present in this failure. Genuine WebIQ project corruption does occur, but it is rare and hard to reproduce, so rule out packaging first.

How do I check compression methods without writing code?

Many archive tools list the method per entry in their details view, labelled Stored or Deflated, and WebIQ needs Deflated on file entries. The Python listing in this article is the unambiguous check: it prints 0 for stored and 8 for deflated, one line per entry, ready to compare against a healthy Runtime Manager export.

Keep reading

  • Troubleshooting

    When an HMI project fails to open: recovery and backup

    A Vijeo Designer project that no longer opens is recovered from the editor's local project storage on the PC, not from the panel. Save never creates a portable backup: close the project in the manager, export it and keep that export as a zip after every working session, then prove the zip by importing it into a clean editor and building.

    HMI and touchscreens

  • Troubleshooting

    E200 HMI recovery when the supplied file is a GOT project

    The E200 is an E-series terminal programmed with E-Designer, and it accepts only a native E-Designer project file with the .MPA extension. GT Designer3 opens GOT projects and can convert E-Designer projects toward the GOT, never the reverse, so recovery means obtaining the original .MPA from the machine builder or a backup, then downloading it over the documented serial cable.

    HMI and touchscreens

  • Checklist

    Checking HMI engineering software before a panel replacement

    Vijeo Designer's current line is 6.2, ending at service pack SP12 (version 6.2.12, 26 January 2024). Newer HMI panels are engineered only in Operator Terminal Expert and cannot be added to Vijeo Designer by updating it. Before ordering a replacement, record your installed version, match the target designation exactly, and let the replacement's documentation decide between a drop-in and a migration.

    HMI and touchscreens