docs · start

Troubleshooting#

Find the phase you are in, then the message you see: each entry quotes Hekma 0.11.0's exact wording, says why it happens, and gives the fix. Most surprises in 0.11.0 come from one fact: Hekma supervises an agent only while a hekma command (or a program that embeds the engine) is running, as Supervision and detached runs explains in full.

When a command fails, its exit code tells you the kind of failure: 2 for a bad command line, 3 for not found, 4 for the wrong state, 5 for something the agent does not support.

Install#

hekma is not found after installing#

The installer prints:

warning: /Users/you/.local/bin is not on PATH. Add it before running hekma.

Why: the installer put hekma and hkm in a folder your shell does not search.

Fix: add that folder to your PATH (for example in ~/.zshrc or ~/.bashrc) and open a new terminal, or install into a folder that is already on it with HEKMA_INSTALL_DIR. To see where the installer would put Hekma without installing anything, set HEKMA_INSTALL_DRY_RUN=1. Install lists every installer setting.

No prebuilt binary for your platform#

error: No prebuilt Hekma binary is available for Linux/aarch64. Install Rust and run: cargo install hekma --force

Why: release archives exist for macOS (Intel and Apple Silicon), Linux x86_64 and Windows x86_64 only.

Fix: install with Cargo, as the message says. If you do not have Rust, install it from rustup.rs first; Hekma needs Rust 1.96.1 or later.

Checksum verification failed#

error: Checksum verification failed for hekma-v0.11.0-aarch64-apple-darwin.tar.gz.

Why: the downloaded archive does not match the checksum published with it. Usually the download was cut short, or a proxy or cache changed it.

Fix: run the installer again. If it keeps failing, download the archive and its .sha256 file from GitHub Releases and compare them yourself before installing.

The installer refuses to overwrite a command#

error: Refusing to overwrite non-Ktesio command at /usr/local/bin/hekma.

The same check can say non-Ktesio executable and name the install folder.

Why: another program called hekma (or hkm) is already on your PATH, and the installer will not replace something that is not Hekma.

Fix: remove the other program if you no longer need it, or install Hekma into another folder with HEKMA_INSTALL_DIR and put that folder earlier on your PATH.

Register#

No adapter.toml found#

✗ No adapter.toml found at '/Users/you/agents/my-agent/adapter.toml'. Point --manifest at a directory containing an adapter.toml, or at the file itself.

Why: --manifest points at a folder with no adapter.toml in it, or at a path that does not exist (then the message names the path as you typed it). Exit code 3.

Fix: pass the folder that holds adapter.toml, or the file itself. Use an absolute path; see Could not read the adapter manifest at start.

The adapter manifest is invalid#

✗ The adapter manifest at '/Users/you/agents/my-agent/adapter.toml' is invalid: adapter.toml is missing the required `[metering]` section. Fix the named section and try again.

The same message names other problems too:

The message saysMeaning
missing the required [lifecycle] sectionNo [lifecycle.start] with an exec.
missing the required [capabilities] section (it declares no supported capabilities)Every capability is unsupported on every OS, or there are none. At least one must be supported somewhere.
missing the required [metering] sectionNo metering source. Every agent needs one.
is not valid TOML: unknown field bogusA key Hekma does not know, usually a typo. Unknown keys are rejected.

Why: Hekma checks the whole manifest before it writes anything, and stops at the first problem. Exit code 1.

Fix: correct the section the message names. The Adapter manifest reference lists every section and field.

Incompatible adapter contract#

✗ The adapter manifest at '/Users/you/agents/my-agent/adapter.toml' cannot load: incompatible adapter contract: manifest declares 2.0.0, engine speaks 1.0.0 — compatible iff the major versions match (contract v1 policy, docs/adapter-contract.md#versioning). Ask the adapter author to retarget the manifest's contract_version to this engine's contract major — see docs/adapter-contract.md.

Why: contract_version has a different major version from the one this Hekma speaks (1).

Fix: set contract_version = "1.0.0" and check the manifest against the Adapter manifest reference. Write the version as three numbers with no v. Adapter contract and conformance kit explains the versioning rules.

Invalid name, unknown kind, or name taken#

✗ Invalid Agent Instance name 'My_Agent': name must start with a lowercase letter or digit ([a-z0-9]). Names must match ^[a-z0-9][a-z0-9_-]*$ (lowercase letters, digits, '_' or '-', not starting with '_' or '-').
✗ Unknown adapter kind 'nope'. Register a native adapter with a known kind (e.g. --kind mock), or supply a manifest adapter with --manifest <path>.
✗ An Agent Instance named 'demo' already exists. Choose a different name, or remove the existing instance with: hekma agent remove demo

Why: names are lowercase letters, digits, - and _, starting with a letter or digit, and unique in the fleet. --kind accepts only the built-in kinds (hermes, acp and mock). Exit code 2.

Fix: choose a valid, unused name. For any other program, use --manifest with an adapter.toml; see Bring your own agent.

Start#

The agent shows failed after a plain start#

hekma agent start NAME printed ✓ Started, but the next command shows the agent failed, and hekma agent show NAME says:

• Failed cause: orphan not found on engine restart (process pid 73923 is gone or was reused); last known: no prior cause recorded

Why: a plain start supervises the agent only while that command runs, and stops it when the command exits, which is almost at once. The start warns you:

• note: the started process is supervised only for this engine session and stops when this command exits; start it with --detach to keep it running across commands.

Fix: start it with hekma agent start NAME --detach, and keep hekma agent logs NAME --follow running beside it so it stays metered and budgeted. See Supervision and detached runs.

The agent exits immediately on a detached start#

✗ Agent Instance 'reader' failed to launch: exited immediately during startup with code 0. The instance is now in the 'failed' state; fix the adapter's launch command and try starting it again.

Why: a detached agent starts with stdin closed. A program that reads input (an interactive tool, a REPL, an ACP agent) sees the end of its input and exits at once. Code 0 means it exited normally, not that it crashed.

Fix: launch the program in a mode that does not wait for input, such as a server or daemon mode, or start it from a program that embeds the engine. If the code is not 0, read hekma agent logs NAME for the agent's own error.

Could not launch the program#

✗ Agent Instance 'noexec' failed to launch: could not launch 'no-such-agent-binary': No such file or directory (os error 2). The instance is now in the 'failed' state; fix the adapter's launch command and try starting it again.

Why: Hekma could not find the program in [lifecycle.start] exec. A bare name is looked up on the PATH of the shell that runs hekma, and a relative path such as ./agent.sh does not work because Hekma starts the agent in its Agent Home.

Fix: use an absolute path in exec, or make sure the program is on PATH for the account and shell that run hekma. Hekma reads the launch command when you register, so after editing exec, remove the agent and register it again.

Could not read the adapter manifest at start#

✗ Could not resolve the adapter to start Agent Instance 'c': could not read the adapter manifest at ./adapter.toml: No such file or directory (os error 2).

Why: the agent was registered with a relative --manifest path, such as .. Hekma 0.11.0 stores the path as typed and reads the manifest again at every start, relative to the folder you run start from.

Fix: remove the agent and register it again with an absolute path: hekma agent register NAME --manifest /full/path/to/my-agent. Until then, running start from the manifest's folder works.

The mock kind has no launch command#

✗ Could not resolve the adapter to start Agent Instance 'demo': native adapter kind 'mock' has no launch command; supply a manifest adapter (its `[lifecycle.start]` exec) to start a real process.

Why: --kind mock exists for trying registration and config. It has nothing to run.

Fix: register a manifest adapter. The Quickstart has a stand-in agent you can copy.

A secret could not be resolved#

✗ Agent Instance 'tk' could not start: secret 'OPENAI_KEY' could not be resolved (tried: environment, secrets file); set the environment variable OPENAI_KEY, or add OPENAI_KEY to the engine secrets file (mode 0600). Nothing was changed; set the secret and start it again.

Why: a config value is secret:OPENAI_KEY, and Hekma found neither an environment variable nor an entry in secrets.toml with that name.

Fix: export the variable in the shell that runs hekma, or add it to secrets.toml in the state directory. See Config, secrets and memory.

The secrets file is not owner-only#

✗ Agent Instance 'tk' could not start: the engine secrets file at '/Users/you/Library/Application Support/ktesio/secrets.toml' is not owner-only (mode 0o644 grants group/other access); fix it with: chmod 600 '/Users/you/Library/Application Support/ktesio/secrets.toml'. Nothing was changed; set the secret and start it again.

Why: on Linux and macOS, Hekma refuses to read a secrets file that other users can read.

Fix: run the chmod 600 command from the message.

Detached start refused for an engine-observed agent#

✗ Agent Instance 'obs' cannot be started with --detach: the instance meters via the engine-observed channel, whose loopback forward listener lives inside the starting command — detaching would leave the agent pointed at a listener that dies with the command. Start it without --detach (the in-command supervision keeps the listener alive), or switch the adapter's metering source to self-reported.. Nothing was changed.

Why: an engine-observed agent sends its model calls through a proxy that lives inside the starting command. Exit code 5.

Fix: run the agent from a program that embeds the engine and stays open, or switch it to self-reported metering if it can print KTESIO_USAGE lines. See Meter token usage.

No upstream provider URL configured#

✗ Agent Instance 'obs' could not start engine-observed metering: no upstream provider URL configured; set `metering.upstream_base_url` to the agent's real OpenAI-compatible endpoint. Nothing was changed; fix the metering configuration and start it again.

Fix: run hekma agent config set NAME metering.upstream_base_url https://api.openai.com (or your provider's URL). See Meter token usage.

Wrong state for the command#

✗ cannot stop an Agent Instance while it is 'registered'. Check the instance's current state with: hekma agent list
✗ Agent Instance 'np' is running. Stop it first, or pass --force to remove it anyway: hekma agent remove np --delete --force

Why: the command does not apply to the agent's current lifecycle state, for example stopping an agent that never started, or removing one that is running. Exit code 4.

Fix: check the state with hekma agent list and run a command that fits it. To remove a running agent, stop it first or pass --force.

Pause is unsupported#

✗ Agent Instance 'np' cannot pause: this agent declares pause 'unsupported' on macos. Inspect its Capability Declaration with: hekma agent show np

Why: the adapter's capability declaration says the agent cannot be paused on this OS. Exit code 5.

Fix: stop the agent instead. If the agent can in fact be paused, change [capabilities.pause] in its adapter and register it again.

A pause does not last#

hekma agent pause NAME succeeds, but the agent is running again straight away:

✓ Paused Agent Instance tk
paused
[hekma] tk: paused detached child resumed at engine release (SIGCONT before the handle was released) — a detached instance is only paused while an engine session holds it; the row is now 'running'

Why: for a detached agent, a pause you request lasts only while the command that paused it runs. Hekma resumes the agent before letting go of it, so it is never left frozen with nobody watching. A pause caused by a budget breach is different and does persist.

Fix: to stop an agent from working, stop it. To hold it paused, pause it from a program that embeds the engine and stays open.

Usage and budgets#

Usage stays at zero#

hekma agent usage NAME shows in 0 / out 0 while the agent is clearly working. Check these causes in order:

  • No command was supervising. Usage a detached agent reports while no hekma command runs is never counted. Keep hekma agent logs NAME --follow running while the agent works.
  • The lines are not reaching Hekma. Run hekma agent logs NAME --follow and look for KTESIO_USAGE lines. They must go to stdout (stderr for ACP agents), start with KTESIO_USAGE and a space, and carry valid JSON with sequence, input_tokens and output_tokens, and no other fields except cached_tokens. A line that breaks a rule is skipped without any message.
  • The same sequence number repeats. Hekma counts each sequence once per run. An agent that always prints "sequence": 0 is counted once.
  • Engine-observed traffic bypasses the proxy. The agent must read the base URL you mapped from metering.base_url. If it uses a hard-coded URL, Hekma never sees its calls.

Meter token usage covers each source in full.

The budget did not stop the agent#

The agent went past its budget and nothing happened.

Why: budgets are checked only while a hekma command holds the engine. Between commands, a detached agent runs with no budget checks, and that usage is not counted later. Also, each cap fires once per run: after you resume an agent paused by a breach, the same cap does not fire again in that run.

Fix: keep hekma agent logs NAME --follow running beside the agent. To re-arm a cap, start a new run. See Budgets and cost.

No dollar figures#

Cost (estimated)  — (no Rate configured — dollar features inert)

Why: Hekma needs both cost.rate.input and cost.rate.output to estimate cost. Without them, dollar caps do nothing.

Fix: set both rates. See Budgets and cost.

A config value is rejected#

✗ unknown config key 'modle'; did you mean 'model'?. Set a known unified key, or use the agent.* pass-through namespace for agent-native extras (e.g. hekma agent config set <name> agent.<key> <value>).
✗ invalid value '10x' for config key 'budget.tokens.cumulative': expected a non-negative whole number of tokens (u64). Nothing was changed. Fix the value and try again.
✗ invalid value '$3' for config key 'cost.rate.input': '$3' is not a valid dollar amount (the whole-dollar part is not a number). Nothing was changed. Fix the value and try again.

Why: Hekma checks keys and values when you set them, and changes nothing if either is wrong. Token budgets are whole numbers; rates and dollar caps are plain decimals with up to six places and no currency sign.

Fix: use a key from Config keys, or put settings for the agent itself under agent., such as agent.temperature.

ACP agents#

Starting without acp.command#

✗ Could not resolve the adapter to start Agent Instance 'oc': no launch command is configured for the acp kind; set the config keys 'acp.command' (required, the ACP agent executable) and 'acp.args' (optional, its arguments) — e.g. `kt agent config set oc acp.command /path/to/agent`.

Why: the acp kind needs to know which program to run. (The example in the message says kt, the CLI's old name; use hekma.)

Fix: set the program and its arguments, for example hekma agent config set oc acp.command opencode and hekma agent config set oc acp.args acp.

An ACP agent ends failed or cannot be reached#

A detached ACP start ends failed, and hekma agent send reports:

✗ Agent Instance 'oc' cannot receive input right now: no live stdin pipe is held for this instance in this engine session (an adopted instance has no recoverable pipe; ...). Durable cross-invocation interaction needs a persistent engine session (planned for a future release); within a single `hekma` process/embedding session this works.

Why: an ACP agent talks to Hekma over its stdin and stdout, and that connection belongs to the process that started it. A detached start closes stdin, so the agent exits; a plain start keeps the connection, but the command exits at once. In 0.11.0, hekma agent send from the command line therefore has no agent to reach. Exit code 5.

Fix: run ACP agents from a program that embeds the engine and stays open; it can start the agent and send prompts. See Run an ACP agent.

ACP usage shows a dash#

• note: oc: no billing-grade usage in the ledger — tiers attempted: observed: not-configured; sentinel: no-lines-seen; no context usage reported (ACP usage_update is context-grain, never billed)

Why: Hekma has no token counts for this ACP agent. The ACP protocol's own usage messages describe how full the agent's context window is, not tokens billed, so Hekma shows them but never counts them as usage.

Fix: either have the agent print KTESIO_USAGE lines on stderr, or set metering.upstream_base_url so Hekma meters its model calls through the proxy. See Run an ACP agent.

Update#

The update check is slow, fails, or is unwanted#

Hekma checks GitHub for a new release at most once an hour, waits at most three seconds, and ignores any failure.

Fix: to turn the check off, set HEKMA_NO_UPDATE_CHECK=1. It is already off when CI is set. See Turn off update checks.

hekma self-update fails#

Why: self-update updates Hekma the way you installed it: brew upgrade ktesio/tap/hekma for Homebrew, cargo install hekma --force for Cargo, or a fresh download for an installer or archive install. It reports any failure from those steps.

Fix: for Homebrew or Cargo, run the command above yourself to see the full error. For a downloaded install, check that you can write to the folder that holds hekma, and retry if the download was cut short. If the checksum keeps failing, download the archive from GitHub Releases and replace the binaries by hand. See Install.