# Troubleshooting

Resolve common configuration and runtime problems.

Start with the final RunResult and the configuration of the process making the request. UI credential indicators and package installation are prerequisite checks, not a service health guarantee.

## The web demo says no API key

Confirm the key is in the SDK repository's .env or the environment used to launch harness-web. An already-set environment value takes precedence over .env. Restart the Python server after editing it.

Choose the provider matching that key. An Anthropic key cannot enable an OpenAI model. Install the selected provider's optional dependency.

## Import or module errors

The import name and the package name are both `harnessx` (`uv add harnessx`). Run examples from a repository clone as modules, through the environment uv created:

~~~bash
uv run python -m examples.simple_chat
~~~

Do not run uv run python -m examples.simple_chat.py. Check that pip and Python belong to the same virtual environment.

## A tool is denied without asking

ASK requires an application approval callback for direct execution. Without a callback the call is denied. Use CliPermissionManager for an explicitly interactive terminal, or implement the callback for your own UI.

In a durable runtime, the run returns `needs_input` and `result.pending` holds the persisted `PendingTool`; call `runtime.approve(pending, resume=True)` or `runtime.decline(pending, resume=True)`. Do not expect a worker process to read stdin.

## Streaming text appears twice

Deduplicate reconnected events using their cursor/identity. Clear provisional text on ATTEMPT_RESET, correlate tool results by tool_call_id, and use the final RunResult output as authoritative.

A lost event subscription does not necessarily stop the underlying run.

## A run cannot safely resume

Rebind the same factory/version, tools, middleware, extension names, and compatible configuration. Do not silently retry an unresolved manual effect. Verify the external outcome, then use resolve_tool.

The database cannot prove an external write did not happen when the process failed after dispatch.

## MCP tools do not appear

Connect the server **before** constructing the agent. `Agent(mcp=manager)` bridges every tool the manager had discovered at that moment and lists their names on `agent.mcp_tools`; an empty tuple means no server was connected yet. A later `register_tools(agent.tools)` call for the same manager is a no-op, and connecting a server name twice raises `ValueError`. Verify command availability, arguments, endpoint transport, and authentication independently.

MCP defaults to ASK. A connection succeeding does not establish that each remote tool is authorized or functional.

## Session disappeared after restart

An ordinary Agent and harness-web chat state are in memory. Use explicit snapshots to restore a conversation or AgentRuntime for execution recovery. The current web demo does not restore chat history automatically.

## An incident is valid but incomplete

Metadata-only or redacted exports can be valid while omitting payloads and artifact bytes. Running or interrupted incidents may also be incomplete. Inspect VerificationReport.issues; validity checks structure and checksums, not business correctness.

An existing output file is not overwritten. Choose a new incident destination.

## A DeprecationWarning names a 0.4 replacement

The 0.3 flat configuration fields, `runtime.execute()`, `runtime.get_status()`, and dictionary access on pending tools still work but warn; they are removed in 0.5. Run the suite once with warnings promoted to errors to find every use, then follow [Migrating to 0.4](../migrating/):

~~~bash
python -W error::DeprecationWarning -m pytest
~~~

## Where to investigate next

- [API reference](../api/) for method contracts.
- [Implementation status](../status/) for known scope limits.
- [Repository issues](https://github.com/datagol/agent-harness-x/issues) to report a reproducible failure without credentials or private payloads.