Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

3.7 KB
Raw Blame

description: "Diagnose missing features, blocked turns, credentials, state paths and lifecycle failures."

Embedding troubleshooting

Use the typed error and the effective capability report together. A method that was compiled out is a different problem from a configured method with a provider failure. Keep credentials, user prompts and raw provider payloads out of routine diagnostics.

Symptom Check and next step
RuntimeError::AlreadyRunning Reuse the process runtime; drop old listeners, agents and runtime before restarting. Profiles require their own process mode.
Method or type not found at compile time Check named Embed Cargo gates, especially mcp/skills. Core compiled flags alone do not activate those facade exports.
CoreError::Unavailable Inspect effective domains/modules as well as compiled features. Runtime selections can narrow a compiled family.
BACKEND_UNAVAILABLE Install the host backend transport, normally through openhuman-tinyhumans, before backend-touching calls.
Credential master-key failure Initialize process master-key state before persisting a runtime API key; check headless key/file setup without printing its value.
Invalid or insecure provider route Supply a nonblank endpoint/key and use HTTPS for remote bearer routes. Loopback fixtures are separate from remote endpoints.
Stack overflow on a nested turn Use the documented Tokio worker stack; the default 2 MiB stack is insufficient. Follow the runnable example support setup.
A write is waiting indefinitely Poll the same agent's approvals or retain an active callback subscription. Check origin, enabled autonomy and trusted action roots.
Streaming appears stalled Drain the bounded progress stream while work runs; inspect the final result. Dropping it cancels forwarding and the turn cooperatively.
A skill is absent Copy a real bundle into the agent's skill directory; symlinked bundles are rejected. New instructions need a new session.
Agent registration returns DuplicateId Another instance or teardown still reserves the ID. Wait for removal/last-handle cleanup to finish.
Retained handle returns AgentRemoved That instance was removed; obtain a newly registered handle rather than reusing the old one.
Decode error on a typed facade Treat it as an API/result-shape mismatch; preserve safe metadata and report a regression.

Inspect without exposing credentials

    let info = runtime.capabilities();
    assert_eq!(info.schema_version, 1);
    assert!(info.defaults.routed_provider);
    let serialized = serde_json::to_string(&info)?;
    assert!(!serialized.contains("sk-test"));
    assert!(!serialized.contains(&provider.uri()));
    assert!(!serialized.contains(&runtime.workspace_dir().display().to_string()));
    println!("{}", serde_json::to_string_pretty(&info)?);

Complete runnable example, including runtime construction, imports and fixture setup.

Before boot, RuntimeBuilder::describe can report a provisional plan; check configuration_resolved. After boot, Runtime::capabilities describes resolved defaults, storage source/driver and selection without its URL/key. Runtime events provide content-free lifecycle metadata, while explicit turn progress can contain text and should be handled accordingly.

Reproduce behavior with offline testing before using a live provider. The error concept explains structured kinds and expected-user-state errors.