[Bug]: TIMEOUT hint tells users to pass --timeout, which adapter commands do not accept
- Dominant language
- JavaScript
- Stars
- 29.3k
- Forks
- 2.9k
- Avg merge
- 15h 36m
- Merged PRs (30d)
- 70
Description
### Description
The default hint on `TimeoutError` tells the user to retry with `--timeout `, but adapter commands do not accept that flag. Following the advice produces a second, unrelated error.
`src/errors.ts:117-126`:
```js
export class TimeoutError extends CliError {
constructor(label: string, seconds: number, hint?: string) {
super(
'TIMEOUT',
`${label} timed out after ${seconds}s`,
hint ?? 'Try again, or increase timeout with --timeout (or OPENCLI_BROWSER_COMMAND_TIMEOUT for the global default)',
EXIT_CODES.TEMPFAIL,
);
}
}
```
Only two commands in the repo declare `--timeout`, and neither is an adapter command:
- `src/cli.ts:2412` — `browser wait`, as `--timeout ` (milliseconds, not seconds)
- `src/cli.ts:3612` — `antigravity serve`, as `--timeout `
The `OPENCLI_BROWSER_COMMAND_TIMEOUT` half of the hint is correct and does work.
### Steps to Reproduce
```bash
# 1. Force a timeout on any adapter command
$ OPENCLI_BROWSER_COMMAND_TIMEOUT=1 opencli xiaohongshu search "opencli" --limit 3
ok: false
error:
code: TIMEOUT
message: xiaohongshu/search timed out after 1s
help: Try again, or increase timeout with --timeout (or OPENCLI_BROWSER_COMMAND_TIMEOUT for the global default)
exitCode: 75
# 2. Follow the advice verbatim
$ opencli xiaohongshu search "opencli" --limit 3 --timeout 90
error: unknown option '--timeout'
$ echo $?
1
```
### Expected Behavior
The hint should only mention mechanisms that exist for the command that timed out. Since `OPENCLI_BROWSER_COMMAND_TIMEOUT` is the actual knob for adapter commands, the simplest correct fix is to drop the `--timeout` clause from the default hint:
```js
hint ?? 'Try again, or raise the global default with OPENCLI_BROWSER_COMMAND_TIMEOUT='
```
Alternatively, if per-command override is intended to be user-facing, adding `--timeout ` to adapter commands would also resolve it — but that is a feature change, whereas the hint is wrong today either way.
Worth noting the unit inconsistency while this is being touched: `browser wait` uses `--timeout ` and `antigravity serve` uses `--timeout `, so a user who does find a working `--timeout` may still pass the wrong magnitude.
### Impact
Cosmetic but squarely in the failure path, where the user is already stuck and most likely to trust the tool's own suggestion. It also misleads agents driving OpenCLI programmatically: the natural recovery is to retry with the flag the error text named, which fails with a different error and a different exit code (1 instead of 75), turning one retryable timeout into an opaque usage error.
Scope: 49 of the `new TimeoutError(...)` call sites pass an explicit `hint` and are unaffected. The default hint is reached from the generic wrapper `runWithTimeout()` at `src/runtime.ts:24-31` (used by adapter command execution) plus a handful of adapters that omit the third argument, e.g. `clis/grok/ask.js:71`, `clis/youtube/search.js:347`, `clis/bilibili/creator-stats.js:84`, `clis/trae-cn/ask.js:89`.
### Environment
- OpenCLI: 1.8.7 (source verified at `90d5070`)
- Extension: 1.0.23 (Browser Bridge connected)
- OS: macOS 26.5 (Darwin 25.5.0, arm64)
Contributor guide
Research direction
Start in src/errors.ts:117-126 and inspect how the default TimeoutError hint is reached through runWithTimeout() in src/runtime.ts:24-31. Reproduce an adapter timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT and verify the resulting guidance names only a valid mechanism, while the 49 call sites with explicit hints remain unaffected.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- cli
- Issue type
- Bug
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100