Troubleshoot by symptom

Record the complete error and the action that produced it, then follow the checks below. Do not repeatedly overwrite files, switch targets, or restart equipment only to remove a message.

Startup and connection

Symptom	Check first	Next step
The desktop app does not reach App Hub	Whether the installation is complete and another Theseus process is already running	Quit completely and reopen; preserve startup logs if it still fails
The local Runtime target is unavailable	The current target and health state in system settings	Switch back to the local target and check again; do not delete the app workspace
A remote target health check fails	Address, network, certificate, and RuntimeHost on the target machine	Follow Connect a Runtime target one check at a time
Qixin is signed in but Run is unavailable	Whether the current Runtime target is connected and authorized	Qixin and target accounts are separate; use the connection prompt on the target row
A browser can open the target but management fails	Trusted HTTPS and the current target-account role	Protected remote operations require the correct connection and Admin permission

AI problems

Symptom	Check first	Next step
No model is available	Qixin sign-in or entitlement, Provider status, and model refresh result	Open the AI Command Center guide
One Provider reports an error	The authentication or network error on that row	Repair that Provider only; healthy Providers do not need to be removed
AI edits the wrong scope	Whether the request states the outcome, scope, constraints, and acceptance checks	Stop the task and ask for an impact list before the smallest repair
AI says it is done but the editor did not change	Actual files, Problems, and the save/conflict state of the open tab	Trust project assets and diagnostics, not the chat claim
A long conversation drifts	Whether unrelated goals were mixed into the same task	Start a new conversation and attach only relevant files with @

Pages and runtime pages

Symptom	Check first	Next step
Runtime reports that no home page is configured	Whether the app has a homePageId	Set the correct page as home under Resources → Pages
The editor is correct but runtime shows older content	Whether the page is saved and whether Graph, PLC, or custom code also changed	Save the page; rebuild resources that require Build/Run
A Page or Component does not open	Schema, widget, method, or expression errors in Problems	Attach the exact error and file with @; ask AI to diagnose before editing
A button does nothing	Whether its action invokes an existing Page Method and diagnostics pass	Check the property-panel binding and Problems; do not place scripts directly in action fields
A page asks for sign-in	Page or widget role requirements and the current app user	Sign in with an app user, not a Runtime target account

Build, runtime, and Graph

Symptom	Check first	Next step
Build is unavailable	Whether the app is Running, Debugging, Paused, or Stopping	Stop safely, then build again
Run or Debug fails	The first specific error in Console and Problems	Locate the Page, Graph, PLC, or Script, repair it, and validate again
A Graph fails to build	Whether nodes, ports, object bindings, and variable references still exist	Ask AI to read current metadata and diagnostics instead of guessing fields
Debug does not stop at a breakpoint	Whether Debug was used and the breakpoint is saved in the current Graph	Save the breakpoint and start Debug from Stopped
Saved logic does not change at runtime	Whether only the editor refreshed while the old instance remained active	Stop, then Run or Debug again so the next instance loads the new assets

Devices, PLC, Pulsar, Vision, and Safety

Symptom	Check first	Next step
AI cannot understand an Axis, IO point, or camera	Whether Object Tree descriptions state physical and business meaning	Have an engineer complete the semantics before AI orchestration
A device method is unavailable	Whether the module is enabled, configuration is saved, and the app was reloaded	Save while Stopped, then explicitly Run or Debug
PLC or a custom method does not appear	Whether the latest app Build succeeded	Repair the build first, then inspect the callable list
Vision cannot generate or verify a version	Camera, inspection, samples, and an image-capable model	Complete each prerequisite; never substitute a fabricated OK result
Safety behavior is unexpected	Inputs, outputs, groups, physical wiring, and safety hardware	Stop equipment and involve a qualified engineer; do not let AI weaken interlocks

Data, import, and Git

Symptom	Check first	Next step
A value disappears after restart	Whether a graph or app variable was used by mistake	Use Choose a data capability to select a saved variable, Recipe, or RecordStore
A Query fails	URL, authentication, parameters, and the external response	Test a read-only request first; production writes require human approval
An imported ZIP cannot run	Home page, module configuration, and assets that require a build	Inspect it in the desktop app and run Build or Run
Git push fails	Current branch, remote, credentials, and uncommitted changes	Follow Collaborate with Git

When asking AI or support to continue

Provide at least:

1. The exact action you were performing.
2. The complete error, not only the last line.
3. The current app state and Runtime target.
4. The earliest relevant error in Problems or Console.
5. @ references to the related Page, Graph, configuration, or Script.
6. Which physical operations are stopped and which remain active.

warning

If equipment behaves unexpectedly, Safety state cannot be trusted, or on-site staff cannot confirm the risk, stop the equipment and follow the site's safety procedure. Do not continue experimenting online.