Skip to main content

🩺 GeneralUpdate Troubleshooting

Comprehensive diagnostic system covering 50+ known issues, all traceable to GitHub/Gitee Issues or code audit findings.

Workflow​

1. Symptom Collection
   β”œβ”€β”€ What is the user's symptom?
   β”œβ”€β”€ Error message/stack trace?
   β”œβ”€β”€ GeneralUpdate version?
   β”œβ”€β”€ Platform (Windows/Linux/macOS)?
   └── Update strategy (Standard/OSS/Silent)?

2. Symptom Matching β†’ Lookup known issues
   β”œβ”€β”€ Match found β†’ Provide root cause + fix + code
   └── No match β†’ Execute 6-step universal diagnostic

3. Provide Fix
   β”œβ”€β”€ Specific code changes, config adjustments, version upgrade suggestions
   └── Preventive measures

4. Verify
   └── Confirm the fix resolves the issue

Symptom Severity Levels​

LevelColorMeaningCount
CπŸ”΄ CriticalBlocking failure, data corruption, security vulnerability8
H🟠 HighScenario blocking, feature failure, upgrade needed11
M🟑 MediumFunctionality degraded, configuration adjustment needed20
LπŸ”΅ LowCode smell, edge cases, known behavior12

C Level (Critical) β€” Blocks Updates​

IssueCauseSolution
Update not startingLaunchAsync() not called / UpgradeApp.exe not deployedEnsure Bootstrap.LaunchAsync() is called in Main()
Method not foundClient and Upgrade NuGet versions differUnify NuGet versions, clean bin/obj and rebuild
Path too long (>260)Windows path limitShorten install path
IPC exposureIPC encryption key hardcodedUse strong AppSecretKey; upgrade to v10.4.6+
Cross-tenant leakageMissing server multi-tenant isolationIndependent ProductId + AppSecretKey per tenant
ZIP traversal writeMalicious ZIP with ../ pathsv10.4.6+ already fixed
BSDIFF integer overflowLarge file diff calculation overflowUse HDiffPatch algorithm
Silent mode not workingProcess exit not triggeredEnsure Close() or Dispose() is called correctly

H Level (High) β€” Severe but Non-Blocking​

IssueCauseSolution
Infinite update loopmanifest.json version not updatedUpgrade to v10.4.6+ (WriteBack fixed)
OSS no update foundBucket config wrong / incorrect versions.jsoncurl test OSS URL
File in useTarget file lockedClose main process before update
SignalR push not respondingConnection dropped or auth failureCheck SignalR Hub status and Token config
Bowl not monitoringProcess name misconfiguredVerify ProcessNameOrId matches actual process

M Level (Medium) β€” Functionality Degraded​

IssueCauseSolution
AOT build failureReflection not adapted for NativeAOTAdd [DynamicDependency] attributes
SignalR reconnection slowRetryDelay too longAdjust retry parameters
Logs not outputtingLog path permission issueCheck %TEMP%/GeneralUpdate/logs/ permissions
Multi-tenant config wrongProductId collisionEnsure unique ProductId per tenant

L Level (Low) β€” Non-Critical​

IssueCauseSolution
Package too largeDifferential not enabledDifferential is embedded in Core, enable PatchEnabled
First update slowCDN cold startWarm up CDN
Config lost after updateBlacklist doesn't include config dirEnsure SkipDirectorys includes config folder

6-Step Universal Diagnostic​

When the issue can't be directly matched, follow these 6 steps:

  1. Version consistency check β€” Are Client and Upgrade NuGet versions the same?
  2. manifest.json verification β€” Does the file exist? Are fields correct?
  3. UpgradeApp existence β€” Is UpgradeApp.exe in the expected directory?
  4. Network accessibility β€” Can you curl the UpdateUrl?
  5. Log analysis β€” Check logs in %TEMP%/GeneralUpdate/logs/
  6. Minimal reproduction β€” Start with Minimal integration, gradually add complexity

Log File Locations​

PlatformDefault Path
Windows%TEMP%/GeneralUpdate/logs/
Linux/tmp/GeneralUpdate/logs/

Security Notes​

  • AppSecretKey management β€” hardcoding in the client is a last resort; prefer startup arguments or environment variables
  • Rotate IPC encryption keys regularly
  • Disable debug logging in production