.agents/skills/release-testing/references/troubleshooting.md
Quick reference for common errors and fixes.
Symptom: CI shows success, but package search seems to find wrong version or nothing matching your release.
Cause: Using .latestVersion from the JSON instead of .version. The feed contains multiple version streams (e.g., 3.119.2 AND 3.119.3), so .latestVersion returns the wrong one.
Fix: Use .version and filter by base version + label from the release branch:
dotnet package search SkiaSharp \
--source "https://aka.ms/skiasharp-eap/index.json" \
--exact-match --prerelease --format json \
| jq -r '.searchResult[].packages[] | select(.id == "SkiaSharp") | .version' \
| grep "^3.119.2-preview.3\."
| ❌ Wrong | ✅ Correct |
|---|---|
.latestVersion | .version |
| No filtering | Filter by {base}-{label}.* |
| Error | Cause | Fix |
|---|---|---|
MAUI workload is required | Missing workload | dotnet workload install maui |
wasm-tools workload is required | Missing workload | dotnet workload install wasm-tools |
SkiaSharpVersion must be specified | Missing version param | Add -p:SkiaSharpVersion=X.Y.Z -p:HarfBuzzSharpVersion=X.Y.Z.N |
| Error | Cause | Fix |
|---|---|---|
Cannot start process 'appium' | Appium not installed | npm install -g appium |
Mac2 driver requires Carthage | Carthage missing | brew install carthage |
Connection refused | Port conflict | Appium auto-starts on 4723; check for conflicts |
Session creation timeout | First run building WDA | Wait - WebDriverAgent builds on first iOS/Mac run |
Invalid bundle identifier | Wrong bundleId | Tests extract from csproj automatically |
| Error | Cause | Fix |
|---|---|---|
No Android devices found | No emulator running | Start emulator first |
Simulator not found | Wrong device name | Check xcrun simctl list devices available |
iOS version not available | Missing runtime | Install via Xcode → Platforms |
System UI isn't responding (Android) | Emulator unstable | Tests auto-retry with dialog dismissal |
# Check if app crashed
adb logcat -d | grep -E "(Force removing|app died)" | tail -5
# Get stack trace
adb logcat -d | grep -E "(AndroidRuntime|FATAL EXCEPTION)" -A15 | head -30
| Log Message | Meaning | Action |
|---|---|---|
Force removing...app died | App crashed | Get stack trace, investigate |
Killing...stop <package> | Normal force-stop | Expected after test completes |
FATAL EXCEPTION | Unhandled exception | Bug - investigate |
Native crash | Native library issue | Bug - investigate |
Old Android may crash due to:
If crash only on old Android: get full stack trace, check if known MAUI/SkiaSharp issue.
xcrun simctl list devices booted # get UDID
xcrun simctl spawn <UDID> log stream --predicate 'process == "YourApp"'
Or use Console.app → select simulator device.
| Symptom | Cause | Fix |
|---|---|---|
| Simulator won't boot | Corrupt state | xcrun simctl erase <UDID> |
| App won't install | Code signing | Check Appium logs |
| Black screen | App crashed | Check simulator logs |
| Error | Cause | Fix |
|---|---|---|
Image similarity too low | Rendering mismatch | INVESTIGATE - potential real bug |
Screenshot is blank/black | Rendering failed | INVESTIGATE - potential real bug |
Failed to decode image | Corrupt screenshot | Check Appium logs for errors |
Resizing actual to match expected | Size mismatch | Normal for different devices - comparison still works |
| Error | Cause | Fix |
|---|---|---|
Executable doesn't exist | Browsers not installed | pwsh playwright.ps1 install chromium |
Target page, context or browser has been closed | Server crashed | Check app build output |
Timeout waiting for selector | App didn't render | Check Blazor app console for errors |
Blazor server failed to start | Env vars from parent | Fixed in test code (ClearDotNetEnvironmentVariables) |
| Error | Cause | Fix |
|---|---|---|
Docker is not available | Docker not installed/running | Install Docker Desktop, start it |
undefined symbol: uuid_generate_random | Using NativeAssets.Linux instead of NoDependencies | Use SkiaSharp.NativeAssets.Linux.NoDependencies |
Fontconfig error: Cannot load default config file | No fontconfig in container | Expected with NoDependencies — not an error |
Cannot connect to the Docker daemon | Docker Desktop not running | Start Docker Desktop |
| Docker image build slow | No layer cache | Normal on first run (~90s), cached after |
If Blazor tests fail with path-related errors, the test infrastructure automatically resolves /var → /private/var in PlatformTestBase.cs.
Scale factor calculated automatically from screenshot size vs window size:
Mac Catalyst uses hardcoded 2x scale factor. Screenshot is full monitor size, element coordinates are app-relative.
"Timed out while enabling automation mode" error:
This is a macOS accessibility permissions issue. The WebDriverAgentMac process needs accessibility permissions to automate apps.
Fixes to try (in order):
tccutil reset AccessibilityThe test includes retry logic (3 attempts) with recovery actions that reset TCC and kill stale processes. If it still fails after retries, it's likely a deeper macOS configuration issue.
Tests include automatic retry for transient failures:
Retryable errors include: