Ignition Designer sends each request through a distinct path. Follow the packet before treating missing projects, script exceptions, and certificate failure as one defect. The installation moved from 8.0.15 to 8.0.16RC1, then restored an 8.0.15 gateway backup after project scripts failed and projects disappeared from the Designer selection screen. A server reboot followed by another restore returned the projects to normal operation. Separate reports describe intermittent client-scope scripting errors on 8.0.16.
Where does each request travel?
Start at layer one. Confirm the Designer workstation and Gateway host have active network interfaces, stable links, and working reachability. Then trace the application path associated with the symptom.
| Function | Request path | Observed stopping point | Address, port, or timing to record |
|---|---|---|---|
| Project discovery | Project files under data/projects → Gateway project loader → Gateway project list → Designer project selection screen |
Projects existed in the directory but did not appear in the Designer selector | Gateway address and configured port used by the affected Designer; startup time; first project-list attempt |
| Project script | Designer or Vision event → Jython project/shared script → Ignition scripting function | A red Designer message box reported Failed to read class descriptor
|
Designer timestamp, project name, script scope, module path, and line number |
| Prepared database operation | Vision Advanced Table edit → onCellEdited → shared module → system.db.runPrepUpdate → database connection → database engine |
The stack reached AbstractDBUtilities.runPrepUpdate; the supplied trace ends before the database engine's decisive nested error |
Event time, database connection name, connection status, query duration, and full nested exception |
| TLS configuration | Browser or client → Gateway TLS listener → configured certificate and private key → certificate-chain validation | After rollback, the previously installed certificate was no longer configured; reconfiguration reported that it could not be verified | Gateway address, TLS port, certificate subject, validity dates, chain, hostname, and host clock |
The project symptom stopped between the on-disk project store and the list presented to Designer. The database trace traveled much farther: the component invoked the extension method, Jython entered the shared module, and the database utility accepted the prepared-call request. These paths require different tests.
Which symptoms belong to which failure domain?
| Symptom | Primary failure domain | Deciding observation | Next diagnostic |
|---|---|---|---|
| Projects absent from Designer selection | Gateway project loading or publication | Project directories remain under data/projects
|
Compare the Gateway's project page with the Designer selector and inspect startup/project-loading logs |
Failed to read class descriptor |
Script loading, compilation, or serialized runtime metadata | Error appears in a red Designer message box while a project script is involved | Capture the complete Designer exception and reproduce from a newly launched Designer session |
system.db.runPrepUpdate exception |
Database call or database response | The trace reaches AbstractDBUtilities.runPrepUpdate
|
Retrieve the deepest exception, check connection health, and execute a controlled test with the same parameter types |
| Client-scope errors appear and disappear | Client session state, loaded script state, or an intermittent downstream dependency | Behavior changes between attempts without a documented script edit | Correlate the same action across a fresh Designer/client session and the existing session |
| Certificate missing after rollback | Gateway TLS configuration and restored configuration state | The certificate is no longer assigned and a new assignment fails verification | Inspect the active certificate, private-key match, chain, hostname, validity interval, trust path, and system time |
Do not use the prepared-update stack as proof of the class-descriptor failure. The first report associated Failed to read class descriptor with a project script involving system.db.runPrepQuery. The separate stack shows system.db.runPrepUpdate. They are different functions and may represent different faults.
Which recovery approaches fit the observations?
| Approach | What it changes | Best use | Limitation |
|---|---|---|---|
| Repeat restore without reboot | Reapplies backup content while the same server runtime remains active | Testing whether the previous restore was incomplete | Repeated attempts still produced missing projects in this installation |
| Restart only the Designer | Clears Designer session and client-side script state | Separating an intermittent client-scope problem from a Gateway-wide problem | Does not reload the Gateway's on-disk project inventory |
Reboot the server, then restore the 8.0.15 backup |
Reinitializes host and Gateway runtime state before applying the known backup | Recovering the installation where projects remain on disk but are not published after rollback | The successful sequence combined two actions, so it does not isolate reboot from the subsequent restore |
Remain on 8.0.16RC1 and troubleshoot scripts individually |
Keeps the upgraded runtime in service | Non-production fault isolation with captured backups and logs | The reported production installation encountered broken scripts and unreliable project visibility |
For the described production recovery, use the sequence that produced a known result: reboot the server and restore the 8.0.15 gateway backup. Treat 8.0.16RC1 and 8.0.16 separately when recording results; the first installation named the release candidate, while another report named the released version.
How should the rollback and restore be performed?
- Record the running Gateway version, the backup's source version, the Gateway address, the configured ports, and the current project directory inventory. Preserve the current logs before restarting.
- Capture the full Designer error, including the timestamp and complete exception text. For database failures, preserve the deepest nested exception rather than only the
AbstractDBUtilitieswrapper. - Schedule the service interruption and close active Designer sessions and clients that could continue writing application data during recovery.
- Reboot the Gateway server. Confirm the operating system has completed startup and that the expected network interface, route, name resolution, and Gateway listener are available.
- Restore the gateway backup created on
8.0.15. Use the normal Gateway backup-restore mechanism and do not manually copy selected project subdirectories into a running Gateway as a substitute for a complete restore. - Allow Gateway startup and project loading to finish. Review the startup log for project-loading, resource-deserialization, module, database, and certificate messages before opening Designer.
- Check the Gateway's project listing first. Then launch a new Designer session and compare its project selection screen with that Gateway-side list.
- Open each affected project and invoke the smallest controlled action that reaches the previously failing project script. Record whether
Failed to read class descriptorreturns.
How do you separate script loading from database failure?
Failed to read class descriptor points to failure while runtime class or script metadata is being read. Test it before involving a database write: start a fresh Designer session, open the project, load the script module, and call a read-only or otherwise controlled entry point that exercises the same import path. Compare that result with the existing session. A failure before the database utility appears in the stack belongs to script loading or execution, not the database engine.
The Advanced Table trace follows this call chain:
onCellEdited
→ updateLineProductionData
→ writeLineProductionInfoToTable
→ system.db.runPrepUpdate
→ AbstractDBUtilities.runPrepUpdateThe shown INSERT contains 25 columns and 25 parameter placeholders, so a simple placeholder-count mismatch is not the visible defect. Several supplied values appear blank. Check each value against the target column's data type and nullability, then retrieve the database driver's innermost message for the rejected value, constraint, connection, or transaction condition. Test the configured connection independently before repeating the component edit.
Match Designer and Gateway logs by timestamp. If the Designer reports a class-descriptor error without a corresponding database request, remain in the script-loading branch. If the Gateway records the prepared operation and a driver exception, follow the database branch.
How should the certificate failure after rollback be handled?
A gateway backup restore can change the active configuration independently of project files. After rollback, inspect which certificate is assigned to the Gateway listener instead of inferring assignment from files remaining on disk.
- Record the exact certificate-verification message and its timestamp.
- Check the Gateway host clock and time zone. Certificate validation uses the current time against the certificate validity interval.
- Compare the requested Gateway hostname with the certificate's permitted names.
- Verify that the private key belongs to the certificate and that the required issuing chain is present.
- Inspect the Gateway log while assigning the certificate. Use the reported validation stage—key, chain, name, validity, or trust—to select the correction.
- After assignment, restart only the service components required by the Gateway's certificate workflow, then reconnect using the configured hostname and TLS port.
Do not bypass certificate verification to make the rollback appear complete. Project recovery and TLS validation are separate acceptance tests.
What proves the Gateway is recovered?
| Check | Pass condition | Failure branch |
|---|---|---|
| Physical and network path | Designer reaches the intended Gateway address and configured listener without intermittent loss | Interface, cable/link, route, name resolution, firewall, or listener |
| On-disk inventory | Expected project directories are present under data/projects
|
Backup content or restore scope |
| Gateway project list | Expected projects appear after startup completes | Gateway project loading, resource parsing, or startup state |
| Designer selector | Fresh Designer session shows the same expected projects | Designer connection target, authentication/visibility, or session state |
| Project scripts | Controlled calls complete without Failed to read class descriptor
|
Script resource loading, imports, or runtime metadata |
| Database operation | Controlled prepared operation completes and the intended row change is confirmed | Connection, value type, nullability, constraint, transaction, or database engine |
| TLS | Client connects using the configured hostname and validates the assigned certificate | Certificate assignment, key, chain, name, validity, trust, or host time |
FAQ
How do I recover Ignition projects missing after a gateway restore?
Confirm the projects exist under data/projects, reboot the server, restore the known 8.0.15 gateway backup, and check the Gateway project list before opening a fresh Designer session.
How do I troubleshoot Failed to read class descriptor in Ignition?
Capture the complete Designer exception, restart Designer, and reproduce the smallest script call that loads the affected project or shared module. If no database request appears in the matching Gateway logs, troubleshoot script loading before the database path.
How do I diagnose system.db.runPrepUpdate after upgrading Ignition?
Follow the stack to the deepest database-driver exception, test the named connection, and compare every prepared value with the target column type and nullability. The shown statement has 25 columns and 25 placeholders, so continue past placeholder count.
How do I fix an Ignition certificate that cannot be verified after rollback?
Check the active certificate assignment, host clock, hostname, validity dates, private-key match, issuing chain, and trust path. Use the Gateway log entry generated during assignment to identify the failed validation stage.
How do I verify an Ignition gateway restore is complete?
Confirm the expected projects appear both on the Gateway and in a fresh Designer selector, run the affected scripts, verify the prepared database operation, and finish by connecting to the configured hostname and validating the assigned TLS certificate.