# Hive.terminal Tools Troubleshooting

Read when a terminal-tools call returned something surprising, empty stdout despite no...

- Repository: https://github.com/aden-hive/hive (11131 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add aden-hive/hive --skill hive.terminal-tools-troubleshooting -g -a claude-code -y`
Codex: `npx skills add aden-hive/hive --skill hive.terminal-tools-troubleshooting -g -a codex -y`
Cursor: `npx skills add aden-hive/hive --skill hive.terminal-tools-troubleshooting -g -a cursor -y`
Gemini CLI: `npx skills add aden-hive/hive --skill hive.terminal-tools-troubleshooting -g -a gemini-cli -y`

## Description

Read when a terminal-tools call returned something surprising, empty stdout despite no error, exit_code is null, output_handle came back expired, "too many jobs" / "session busy" / "too many PTYs", warning was set unexpectedly, semantic_status disagrees with exit_code. Diagnostic recipes only, load on demand. Don't preload; the foundational skill covers the happy path.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Troubleshooting terminal-tools

Recipes for surprising results. Match the symptom to the section.

## Empty `stdout` despite the command "should have" produced output

Possible causes:
1. Output went to **stderr** instead. Check `stderr` in the envelope (or use `merge_stderr=True` for jobs).
2. Output was **fully truncated** because `max_output_kb` is too small. Check `stdout_truncated_bytes > 0`. Bump `max_output_kb` or paginate via `output_handle`.
3. Command produced no output (correct, just unexpected, `silent` flags, no matches).
4. Pipeline issue: the last stage of a pipe ran but stdout went elsewhere (`> /dev/null`, redirected via `2>&1`).
5. Process is buffering its output and didn't flush before exit. Add `stdbuf -oL` (line-buffered) or `unbuffer` to the command.

## `exit_code: null`

| Cause | Other field |
|---|---|
| Auto-backgrounded | `auto_backgrounded: true, job_id: <X>` |
| Hard timeout, process killed | `timed_out: true` |
| Pre-spawn failure (command not found) | `error: ...` set, `pid: null` |
| Still running (in `terminal_job_logs`) | `status: "running"` |

## `output_handle` returned `expired: true`

5-minute TTL. Either (a) you waited too long, or (b) the store evicted it under memory pressure (64 MB total cap, LRU eviction). Re-run the command.

To reduce risk: paginate the handle as soon as you receive it, or use `terminal_job_*` for huge outputs (4 MB ring buffer with offsets, no expiry).

## "too many jobs" / `JobLimitExceeded`

`TERMINAL_TOOLS_MAX_JOBS` (default 32) hit. Either:
- Wait for jobs to exit (poll with `terminal_job_logs(wait_until_exit=True)`)
- Kill old jobs: `terminal_job_manage(action="list")` to see what's running, then `signal_term` the abandoned ones
- Raise the cap via env (rare)

## "session busy"

A `terminal_pty_run` was issued while another `_run` is in flight on the same session. PTY sessions are single-threaded conversations. Wait for the prior call to return, or open a second session.

## "PTY cap reached"

The rest: https://github.com/aden-hive/hive/blob/HEAD/core/framework/skills/_preset_skills/terminal-tools-troubleshooting/SKILL.md