# Get help and file useful bugs When a run fails, the fastest path to a fix is a report we can act on without a second round of questions. This page covers what to gather, where to send it, and what to check first so that many problems never need a report at all. ## What to include in a bug report A useful report lets us follow the run with you. Four items make that possible: 1. Attach `hank.json`, the hank – the workflow definition – with `env`, `requirements.env`, and embedded keys redacted. 2. Include the execution directory path. It has the form `~/.hankweave-executions//`; startup prints `New execution: `, and that ID forms the directory name. 3. Include the contents of `/.hankweave/state.json`. It records progress for each codon – one sealed agent task in the sequence – along with budget state and failure information. Its full schema belongs to [the state-file reference](/reference/state-file). 4. Include the exact error text from the console or log, whether the run was interactive (a TUI, or terminal interface) or headless (without the TUI, for CI/CD and scripts), and the `hankweave --version` output. Preserve the surrounding evidence too. The execution directory contains `agentRoot/`, `.hankweave/checkpoints/`, `.hankweave/events/events.jsonl`, and `.hankweave/runtime.lock`. The exact agent-log path is recorded as `claudeLogPath` in `state.json`; follow the log-inspection procedure in [observe and debug](/operate/observe-and-debug). > **Pitfall:** Redact `env`, `requirements.env`, and embedded keys before sharing `hank.json`. Values there are plaintext. Authentication failures are a common first-run problem, and they show why the exact error text matters. For the default direct-Anthropic Claude route, the startup self-test requires `ANTHROPIC_API_KEY`; a local Claude Code login alone is not a substitute. The credential-presence check is not proof that the credential is valid. The captured failure below is the kind of diagnostic to preserve verbatim: ```text ╭────────────────────────────────────────────────────────────────────╮ │ Hankweave v0.10.0 │ │ darwin arm64 • node v23.8.0 │ ╰────────────────────────────────────────────────────────────────────╯ Created new execution directory: ~/.hankweave-executions/ New execution: Source → data Exec → ~/.hankweave-executions/ SDKs → Claude node_modules ✓ [] [ERROR] Self-test completed: FAILED [] [ERROR] Self-test FAILED: Some checks failed [] [ERROR] - authentication: ✗ No authentication found (set ANTHROPIC_API_KEY) [ERROR] Server startup failed! Error message: Self-test failed for 1 model(s): - Claude Haiku 4.5 (latest) (anthropic/claude-haiku-4-5): Some checks failed • authentication: No authentication found (set ANTHROPIC_API_KEY) Stack trace: Error: Self-test failed for 1 model(s): - Claude Haiku 4.5 (latest) (anthropic/claude-haiku-4-5): Some checks failed • authentication: No authentication found (set ANTHROPIC_API_KEY) at eU (file:///build/runtime/0.10.0/node_modules/hankweave/dist/index.js:260:5401) at async Egt (file:///build/runtime/0.10.0/node_modules/hankweave/dist/index.js:842:647) at async file:///build/runtime/0.10.0/node_modules/hankweave/dist/index.js:843:754 exit=1 ``` This capture normalizes timestamps, execution IDs, and workspace paths as ``, ``, and ``; use the corresponding values from your own run and do not paste private paths. The run banner is `Hankweave v0.10.0 / darwin arm64 • node v23.8.0`; the platform, architecture, and Node version vary by machine. The version string is the other piece of identity every report needs. Get it with: ```text hankweave --version ``` ```text 0.10.0 ``` `hankweave --version` prints the bare version string to stdout and exits with code 0. Include that output verbatim in every report, alongside the run banner. The `--help` excerpt later on this page labels `Saved lockfile` as stderr; it is separate from the bare version string. When you describe how to reproduce the run, give the exact command. Use an explicit path: ```text hankweave ./my-hank.json ./data ``` This runs a hank directly. Hankweave has no subcommands. With no arguments, the runtime launches the welcome wizard rather than running a hank. The captured help text below contains a conflicting bare-invocation example; use the explicit path for a direct reproduction while the discrepancy remains. Keep these runtime details with the report. Outputs stay in `agentRoot/` by default; there is no default `hankweave-results` directory. See the [runbook](/operate/runbook) for the complete output-directory behavior. If a flag is absent from `--help`, it may be `--replay`, `--max-cost`, `--max-time`, `--without-proxy`, or `--ignore-data-mismatch`; check the [CLI reference](/reference/cli) for their documented forms and the help-parity note. `--attach` is boolean: use `--attach --port 8080` or `--attach --execution ` to connect read-only to a running server. ## How to reach the team File runtime bugs at the [Hankweave issue tracker](https://github.com/SouthBridgeAI/hankweave-runtime/issues). The canonical documentation home is [hankweave.southbridge.ai](https://hankweave.southbridge.ai). Send runtime contributions through the [runtime repository](https://github.com/SouthBridgeAI/hankweave-runtime). Send documentation contributions through the [documentation pipeline](/contribute/documentation-pipeline). The issue tracker belongs to the release this page describes. Its identity is: | Release identity | Value | | ---------------- | ---------------------------------------------------- | | npm package | `hankweave` | | repository | `https://github.com/SouthBridgeAI/hankweave-runtime` | | tag | `v0.10.0` | | commit | `d0f0a86` | ### Compare the locked command reference The locked package requires Node ≥22.19.0. For command-reference details, the full `--help` output is the capture for this release. It includes the version banner, argument-inference rules, five option groups, 26 documented flags, the three-tier safety system, and six examples; use the [CLI reference](/reference/cli) for the maintained flag inventory. When a run will not start, try `--validate` first; the full validation workflow belongs to the [runbook](/operate/runbook). Here is the output body of `hankweave --help` at this version, without the colored startup banner. You can compare the banner text above and its box in the authentication-failure capture. ```text Hankweave Runtime - Codon Orchestration Usage: hankweave [options] [config-or-data-path] Arguments: config-or-data-path Path to hank.json or project directory When only one argument provided: - If ends with .json: treated as hank-path - Otherwise: treated as data-path Execution Control: -e, --execution Use specific execution directory Creates if doesn't exist, resumes if has state -n, --new, --start-new Start new execution, never resume Use -n -f to overwrite existing state -f, --force Override safety checks (hash mismatch, existing state) --no-wipe With --start-new --force, preserve the existing agentRoot/ workspace instead of wiping it -y Non-interactive mode, skip confirmation prompts Output: -o, --output Copy outputs to this path (default: stay in execution dir) --overwrite-output Overwrite existing output files instead of renaming Configuration: --config Path to hank.json (alternative to positional arg) --data Path to data source (default: config directory) -i, --input Use inline text as data input (highest priority) -m, --model Model override (sonnet|opus|gemini-flash|etc) Server: -p, --port WebSocket server port (default: auto-select free port) --headless Run without TUI (for CI/CD and scripts) --no-autostart Don't automatically start codons --proxy Enable the LLM proxy server (disabled by default) --anthropic-base-url Custom Anthropic API base URL --idle-timeout Idle timeout for WebSocket and proxy servers (0-255, default: 0) --shim-idle-timeout Harness idle timeout in seconds (default: 120, per-codon) Other: --init Initialize a new hank in current directory -v, --validate Validate configuration without running --cleanup Remove execution artifacts --copy Copy data instead of symlinking (for compatibility) --ignore-rig-failures Ignore rig setup failures --attach Connect TUI to an already-running server (read-only mode) -h, --help Show this help --version Show version Execution Safety: Hankweave implements a three-tier safety system for execution directories: - Tier 1: Cannot use ~/.hankweave-executions/ directly (reserved for auto-managed) - Tier 2: Directories with existing .hankweave/ require --force (backs up existing) - Tier 3: Non-empty directories show warning and prompt for confirmation Examples: hankweave Run with hank.json in current directory hankweave ./my-project Run project, resume if possible hankweave ./my-project -n Start fresh execution (--new) hankweave -e ./my-exec Use specific execution directory hankweave -o ./results Copy outputs to ./results hankweave -m opus -p 8080 Use opus model on port 8080 Outputs are stored in the agent workspace (~/.hankweave-executions/{id}/agentRoot) by default. Use --output to copy them elsewhere. --- stderr --- Saved lockfile ``` ## What issue #1 taught about first runs Issue #1 documented a model-selection failure involving a retired health-check model and the `GOOGLE_API_KEY` → `GEMINI_API_KEY` rename. For the full account, read the [issue #1 postmortem](https://github.com/SouthBridgeAI/hankweave-runtime/issues/1). To distinguish codon self-tests from provider health checks and choose the next check, use the decision table in [authentication and models](/operate/authentication-and-models). At 0.10.0, the `model_catalog` preflight checks at config load whether each codon's resolved model is servable by Pi – the check uses Pi's model catalog – and rejects a model known to the registry but unavailable to Pi, suggesting alternatives before any API call. > **VersionNote:** The `model_catalog` preflight was added in 0.10.0 in response to issue #1. An older runtime may fail without this diagnostic. For a first-run `Model not found`, follow this order: 1. Run `hankweave --validate` and read the catalog-preflight diagnostic. 2. Check the model spelling against [model resolution](/reference/model-resolution). 3. Check the provider key name in the [provider key table](/operate/authentication-and-models), including the `GEMINI_API_KEY` rename. ## Before you file Start with your error text in [troubleshooting](/operate/troubleshooting), then follow it to the phase, cause, and fix. The entries are based on captured failure fixtures. If you want to understand a design choice, try the [FAQ](/faq): names, obsolescence, secrets, MCPs, skills, and parallel agents. You do not need a bug report to ask why something works this way. At 0.10.0, `--validate` self-tests are local: SDK import, credential presence, and Pi catalog lookup. They make no billable API call. The welcome wizard's pre-demo credit check is the one-token API call, not `--validate`. There is no `--verbose` flag in the locked command surface. For pre-run checks, use `--validate`; for failures during a run, use the event journal at `.hankweave/events/events.jsonl`. See [the event journal](/integrate/event-journal). If the problem remains, bring us the exact error, execution evidence, version output, and interactive-or-headless distinction at the [issue tracker](https://github.com/SouthBridgeAI/hankweave-runtime/issues). Those details give us a place to start together.