#5046: schtasks: add helpful hint for 'stub received bad data' error
app: macos
gateway
Cluster:
Cross-Platform Fixes
## Summary
Adds a helpful troubleshooting hint when users encounter the "stub received bad data" (0x6F7) error during Windows Task Scheduler service installation.
## Problem
On Windows 11 Home (and potentially other editions), users can encounter the error:
```
Gateway service install failed: schtasks create failed: ERROR: The stub received bad data.
```
This is Windows error code 0x6F7 (RPC_E_INVALID_DATA) and typically indicates Task Scheduler service issues rather than a problem with OpenClaw itself.
## Solution
Added a new `resolveSchtasksErrorHint()` function that provides specific hints based on the error message:
1. **For "stub received bad data" errors**: Suggests restarting the Task Scheduler service, running from elevated PowerShell, or using manual gateway run as a fallback.
2. **For "access is denied" errors**: Existing hint suggesting elevated PowerShell.
## Changes
- Added `resolveSchtasksErrorHint()` function in `src/daemon/schtasks.ts`
- Updated error handling to use the new function
- Added tests for the new function in `src/daemon/schtasks.test.ts`
## Testing
- All existing tests pass
- Added 3 new tests for `resolveSchtasksErrorHint()`
- Linting passes
- Type checking passes
Closes #5026
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds a small error-message improvement for Windows Task Scheduler installation failures by factoring hint generation into `resolveSchtasksErrorHint()` and adding unit tests. It also includes unrelated changes: macOS exec approval prompt UI tweaks and a legacy config migration adjustment to allow custom `audio.transcription` command paths.
The schtasks changes integrate into the existing `installScheduledTask()` error path by appending a contextual hint to the thrown error when `schtasks /Create` fails, improving troubleshooting without altering the scheduler logic itself.
<h3>Confidence Score: 4/5</h3>
- This PR is likely safe to merge with low functional risk.
- The primary change is additive (string hinting + tests) and the integration point is localized to the `schtasks` failure path. The main area to double-check is the broadened legacy migration behavior for `audio.transcription`, which changes what legacy configs will be accepted/migrated.
- src/config/legacy.shared.ts; src/config/legacy.migrations.part-2.ts
<!-- greptile_other_comments_section -->
**Context used:**
- Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=fd949e91-5c3a-4ab5-90a1-cbe184fd6ce8))
- Context from `dashboard` - AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=0d0c8278-ef8e-4d6c-ab21-f5527e322f13))
<!-- /greptile_comment -->
Most Similar PRs
#19504: fix(gateway): avoid stale running status from Windows Scheduled Task
by Fologan · 2026-02-17
78.4%
#5496: Fix: Windows path separators stripped in Gateway scheduled task
by giuliozelante · 2026-01-31
78.3%
#5077: fix(windows): implement reliable gateway restart via schtasks helper
by romeoscript · 2026-01-31
73.9%
#18952: fix: sanitize schtasks env vars to prevent CRLF command injection
by coygeek · 2026-02-17
73.3%
#9173: Fix: Improve error messaging for API rate limits and billing errors
by vishaltandale00 · 2026-02-04
71.7%
#22066: fix(cli): add actionable hints for gateway close errors
by pierreeurope · 2026-02-20
71.2%
#18792: docs: add macOS source-run troubleshooting for setup/auth issues
by yash27-lab · 2026-02-17
71.1%
#7085: test: skip flaky workspace-paths & safe-bins tests on non-Linux/CI ...
by ThinkIbrokeIt · 2026-02-02
71.1%
#8642: fix: improve launchctl bootstrap error messages for GUI domain issues
by dbottme · 2026-02-04
70.7%
#7507: test(ci): make tests cross-platform (Windows) + add basic sanitizat...
by ThinkIbrokeIt · 2026-02-02
70.5%