Facade CodeTroubleshooting
Find out whether a problem comes from the launch setup, the CLI, or its model provider.
Check the requested launch
Run Show Agent Launch from the Command Palette and choose the working location. The report shows how each CLI would start there now: executable, directory, arguments, and environment variable names. Private values are hidden.
The report describes the next start with your current settings. It does not describe an agent already running. If a request succeeds, provider usage records can help confirm which account handled it.
Find the symptom
| Problem | What to check |
|---|---|
| You cannot find the settings file | Choose Open Settings, then Edit in facade.json under Facade: Home. If the remote window opens Settings as JSON, the command opens facade.json directly. |
| An entry is missing from New Agent | Check the entry’s name and type, and make sure it is not disabled with enabled: false. Invalid entries appear under Unavailable with a reason. |
| The executable cannot be found | Install the CLI where the project runs, or set its full path in command. For OpenCode, use version 2 (@opencode/cli). |
| An environment reference is missing | The editor host must have that variable before the agent starts. Exporting it in an existing terminal does not update the host. |
| An argument conflicts with an option Facade controls | Remove the option from args. Use the model, effort, or top-level yolo field instead. |
| Authentication fails or a model is unavailable | Check the provider’s key, endpoint, region, model ID, and account access. |
| A Codex provider does not respond | Confirm that its endpoint supports the Responses API. |
| An agent cannot find another agent | Check that their projects are connected through the same Facade home and their access settings allow communication. |
| A custom program receives no messages | Type into its terminal. Custom entries do not receive Facade messaging or tools. |
| Saved settings have not changed a running agent | Start a new agent. To keep the conversation, end the agent, then use Resume Agent to restart it with the new settings. |
For SSH setup, see Run agents on a remote machine. For phone connection errors, see Continue from your phone.
Report a problem
Include what you tried, the exact error, your operating system, editor and extension versions, CLI version, and selected entry. If possible, include the relevant settings with keys and private values removed.