Skip to main content

🩺 GeneralUpdate Troubleshooting

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

πŸ“‹ User Symptom Collection​

### Required Information
- Symptom description: ______
- Error message/stack trace: ______
- GeneralUpdate version: ______
- Platform: ______ (Windows / Linux / macOS)
- .NET version: ______
- Update strategy: ______ (Standard / OSS / Silent / Differential / CVP / Push)
- Recent config changes: ______ (Yes/No, what changed)

### Optional Information
- Any ExceptionEventArgs in event listeners: ______
- Any logs (Logs/generalupdate-trace-*.log): ______
- Issue reproducible: ______ (Yes/No, frequency)
- First occurrence: ______

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
   β”œβ”€β”€ Priority: python3 scripts/search.py "<symptom>" --domain issue
   β”‚   └── Matched β†’ Provide root cause + fix + code
   └── No match β†’ Fall back to reference.md full text search

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

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

Prefer using the BM25 search engine for precise matching of known issues:

# Natural language search for known issues
python3 .claude/skills/generalupdate-troubleshoot/scripts/search.py "update succeeded but app crashes" --domain issue
python3 .claude/skills/generalupdate-troubleshoot/scripts/search.py "method not found" --domain issue
python3 .claude/skills/generalupdate-troubleshoot/scripts/search.py "garbled Chinese text" --domain issue

# Search for strategy-related issues
python3 .claude/skills/generalupdate-troubleshoot/scripts/search.py "OSS permission error" --domain strategy

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

Full list available in reference.md

βœ… Universal Pre-Diagnosis Checklist​

Runtime Environment Check​

  • Target machine has correct .NET runtime installed (matches publish framework)
  • Target machine has write permissions (InstallPath directory writable)
  • Firewall not blocking UpdateUrl communication port
  • Sufficient disk space (at least 2Γ— update package size)
  • Linux/macOS: UpgradeApp has chmod +x executable permissions

Version Check​

  • Client and Upgrade projects use the exact same NuGet version
  • Server returns version numbers in 4-part format (e.g. 1.0.0.0)
  • manifest.json mainAppName matches actual process name
  • AppType set correctly (Client = 1, Upgrade = 2)

Configuration Check​

  • All 6 required UpdateRequest fields are set
  • UpdateUrl accessible via HTTP GET returning valid JSON
  • AppSecretKey matches server config (length β‰₯ 16 characters)
  • UpgradeApp.exe exists in update/ subdirectory of publish directory

Log Check​

  • Check Logs/generalupdate-trace-*.log (if available)
  • Check ExceptionEventArgs in event listeners
  • Check MultiDownloadErrorEventArgs for exceptions

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 Directories 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 Logs/generalupdate-trace-*.log
  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

⚠️ Anti-Pattern Checklist​

#Anti-PatternConsequenceCorrect Approach
1Only looking at error messages, not eventsMissing detailed info in ExceptionEventArgsSubscribe to all 7 events
2Assuming no logs because wrong pathMissing critical diagnostic infoCheck InstallPath/Logs directory
3Only checking Client, not Upgrade processIssue is in Upgrade but diagnosis goes wrongCheck both processes
4Modifying code for update issues immediatelyIssue might be server config, not client bugCheck server version info first
5Ignoring NuGet version consistency"Method not found" root cause is version mismatchCheck versions first
6Testing only in Debug environmentRelease may lack runtime filesReproduce in release/production environment
  • /generalupdate-init β€” Bootstrap configuration
  • /generalupdate-ui β€” Update UI diagnostics
  • /generalupdate-strategy β€” Strategy-related issues
  • /generalupdate-advanced β€” Advanced feature issues