Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
175 lines (126 loc) · 6.08 KB

TROUBLESHOOTING.md

File metadata and controls

175 lines (126 loc) · 6.08 KB
Raw

Troubleshooting

The editor launcher is the normal browser workflow:

bun run ui -- --project /path/to/target-project

Run it from the Alonzo source checkout, not from the target project. Keep that terminal open while using the editor. It starts and stops OpenCode, the controller, and the editor together.

Start With These Checks

  1. Confirm the source checkout has its dependencies:

    bun install

  2. Confirm the target path exists and Alonzo is installed there:

    bun scripts/install-opencode-template.ts /path/to/target-project

    The installer creates .opencode/plugins/alonzo.ts, the /alonzo command, skills, and starter workflows. It leaves any existing opencode.json untouched.

  3. Confirm OpenCode is available:

    opencode --version

  4. Start the editor stack once. Do not separately start OpenCode for the same project and ports.

The Launcher Says Alonzo Is Not Installed

The target project does not contain the local plugin wrapper, or the launcher was pointed at the wrong directory. Run the installer from the source checkout:

bun scripts/install-opencode-template.ts /path/to/target-project

If the target already has opencode.json, leave it in place. The installer adds Alonzo beneath .opencode/ without modifying the existing configuration.

OpenCode Does Not Start In The Target Project

Read the launcher terminal from the first error. Common causes are:

  • opencode is not on PATH: install OpenCode or set OPENCODE_BIN to its executable path before starting the launcher.
  • The target project's opencode.json is invalid: run opencode directly from that project to see the configuration error, fix it, then stop that TUI and retry the launcher.
  • The source checkout was moved after installation: rerun the installer so the generated .opencode/plugins/alonzo.ts wrapper points at the current checkout.
  • Another OpenCode process already owns the configured port: stop it or use a different three-port set as described below.

A Port Is Already In Use

The launcher reserves three different loopback ports before starting: OpenCode 4096, controller 4097, and editor 5173. First stop the previous launcher with Ctrl+C in its terminal. If that terminal is gone, identify the listener before killing it.

On Windows PowerShell:

Get-NetTCPConnection -State Listen -LocalPort 4096,4097,5173 |
  Select-Object LocalPort, OwningProcess
Get-Process -Id <pid>
Stop-Process -Id <pid>

On macOS or Linux:

lsof -nP -iTCP:4096 -sTCP:LISTEN
lsof -nP -iTCP:4097 -sTCP:LISTEN
lsof -nP -iTCP:5173 -sTCP:LISTEN
kill <pid>

Verify the process is an old OpenCode, controller, or Vite instance before stopping it. If it belongs to another application, leave it running and select three unused ports instead:

bun run ui -- --project /path/to/target-project \
  --opencode-port 4098 \
  --controller-port 4099 \
  --editor-port 5174

All three port values must be different.

The Editor Cannot Connect Or Shows No Server

  1. Keep the launcher terminal open and check it reached Alonzo editor is ready.
  2. Open the exact URL printed by the launcher. It is usually http://127.0.0.1:5173.
  3. Stop the launcher with Ctrl+C, wait for it to exit, then start it again.
  4. If the launcher reports that the bridge did not initialize, check the OpenCode startup error above. A fresh launcher restart is safer than manually starting only one of its child processes.

The Editor Shows No Workflows

The editor lists only direct workflows/*.alonzo.yaml files in its target project. The installer adds ping.alonzo.yaml. Copy other examples, including hey.alonzo.yaml, from this checkout into the target project's workflows/ directory; nested files and source-checkout examples are not listed automatically.

A Previous Run Is Still Listed

OpenCode keeps completed workflow parent sessions in its local session history, and the editor remembers the last selected workflow and session in browser site data. This can make a previous run remain selectable after a launcher restart.

Only active in-memory workflow runs replay trace entries after a browser reconnect. Alonzo does not scan .opencode/alonzo/.alonzo/trace/ on startup, so old trace files are diagnostics, not replay input.

To return to a fresh editor view, select another workflow or refresh the page. If the browser continues to select an unwanted historical session, clear site data for the editor origin, normally http://127.0.0.1:5173, then reopen the editor. This clears saved editor selection and prompts; it does not delete workflows, OpenCode session history, or runtime diagnostics.

Keep .opencode/alonzo/.alonzo/trace/ and human/ until you have reviewed any failure or gate evidence. Delete individual runtime artifacts only when you intentionally want to discard those diagnostics.

/alonzo Is Normal Text In The TUI

The TUI command is separate from the editor launcher. Confirm the target project has the generated .opencode/ integration, then start the TUI from that target project:

cd /path/to/target-project
opencode

Enter /alonzo workflows/ping.alonzo.yaml in that TUI. If it is still treated as normal text, inspect the project's OpenCode configuration and plugin wrapper.

A Model Fails

Check that the selected model is available in the target project's OpenCode providers, or update the affected node configuration. Start a new run after the change; Alonzo does not silently switch models.

A Workflow Waits At A Gate

Submit the requested response in the editor or TUI. File fallback requests and responses are under .opencode/alonzo/.alonzo/human/ in the target project.

A Workflow Halts

Inspect the editor Logs tab and traces under .opencode/alonzo/.alonzo/trace/. Fix the node configuration or prompt and start a new run. Provider errors halt the workflow rather than changing the model or rewriting the workflow.

Before Sharing Diagnostics

Traces, handoffs, messages, gate files, and bridge records can contain project content or local authentication information. Review them before sharing.