Troubleshooting

Recover from you-agent-factory install, run, configuration, MCP, and dynamic-workflow failures with short symptom-scoped guidance that links to the owning canonical docs.

you Not Found After Install

Symptom: your shell reports you: command not found, or which you finds nothing, after you ran an install script. Recovery: open a new terminal so PATH reloads, then confirm you resolves. If the binary is still missing, re-run the install script for your operating system and confirm the script finished without error before retrying you. For the full OS install paths and the provider step that follows, open Install.

Install

OS Install Or Provider Setup Confusion

Symptom: the install path does not match your OS, or you are unsure what to configure after install. Recovery: use the macOS/Linux curl script or the Windows PowerShell script for your machine, then run you init to record the provider that executes your workers, or you init --provider <name> to set it non-interactively. Do not mix OS install entrypoints. For the install reference and first-run order, open Install and Run Your First Factory.

Submit Or Work Against A Factory That Is Not Live

Symptom: you session list is empty, or the host connection fails, when you try to submit or inspect work. Recovery: start or attach a factory with you or you run first, then confirm a live Factory Session with you session list before you submit. An empty list means the host responded but no session is registered yet; a connection failure means nothing is listening—start the factory and retry. For session liveness and the broader command matrix, open Factory Session, Run Your First Factory, and CLI.

Operator Defaults Fail At Startup

Symptom: the factory fails before dispatch with a config-path error, an unsupported workerModelProvider summary, or DEFAULT resolution guidance—or you expected operator defaults and nothing applied. Recovery: a missing ~/.you-agent-factory/config.json is valid and applies no defaults; create the file only when you want defaults.workerModelProvider and defaults.workerModel. Fix malformed JSON so the file parses, replace unsupported providers with an accepted value, and never leave DEFAULT without a concrete lower-precedence provider from file, env, or flag. For operator-default failure modes and named factories, open Global Configuration Factories; for factory.json topology, open Configuration.

MCP Host Cannot Resolve you On PATH

Symptom: the MCP host fails to spawn you mcp serve because command you is not found on the host PATH. Recovery: set the host command field to the absolute path of the you binary instead of relying on the shell PATH, keep args as mcp serve, then reload the host so the child process respawns. For host JSON shape and serve modes, open MCP; for a Cursor first-loop walkthrough, open the Cursor dynamic workflows guide.

MCP Sources Fail Because cwd Is Wrong

Symptom: validate or start fails to resolve workflow sources even though the MCP child process starts. Recovery: set cwd to the absolute path of the workflow or project root whose sources Factory Session tools should resolve—not a nested package, home directory, or unrelated checkout—then retry validate. For host cwd notes, open MCP; for dynamic-workflow source and configuration depth, open Dynamic Workflows.

MCP Host Not Reloaded After Config Save

Symptom: you saved MCP host configuration, but Factory Session tools still do not appear under you.factory_session.* names. Recovery: restart the host or run its reload-window action so it respawns the MCP child process—saving the file alone is not enough for most hosts. After reload, confirm the tools appear before calling validate or start. For reload and tool discovery, open MCP; for Cursor reload steps, open the Cursor dynamic workflows guide.

Cursor Dynamic Workflow Loop Fails

Symptom: Cursor cannot complete a first Factory Session loop—tools missing after MCP setup, validate_source fails, or start/status never reaches a live session. Recovery: confirm you mcp serve is configured with an absolute command path when needed, cwd at the workflow project root, and a host reload after every MCP config change, then retry validate → start → status or result. Treat the Cursor guide as the first-loop walkthrough; open Dynamic Workflows and MCP when you need API or host-contract depth beyond that loop.

Limits And Assumptions

Troubleshooting is a recovery lookup for you-agent-factory failure modes. It is not the install command matrix, not the first-run walkthrough, not a full CLI flag dump, not the configuration or global-configuration-factories deep dive, not MCP host setup, not dynamic-workflow authoring, and not a sync of packaged you docs. Sibling links aid discovery only; they are not required to understand the short recovery actions here.