alforria

Troubleshooting

Diagnose provider, configuration, server, snapshot, and terminal problems.

Start with the version and the resolved paths:

alforria --version
alforria debug paths
alforria debug config

debug config prints the merged configuration after every source is applied. debug paths shows the config, data, cache, and state directories in use.

No models are listed

alforria auth list
alforria models
alforria models --refresh
  • If the provider is missing, connect it with alforria auth login.
  • If the catalog is empty or stale, refresh it. Without network access, set OPENCODE_DISABLE_MODELS_FETCH=1 and point OPENCODE_MODELS_PATH at a local catalog file.
  • LibertAI models come from the built-in catalog and https://api.libertai.io/v1. Check that your account has access with alforria libertai usage.

Model not found

Model ids use provider/model. Copy the exact id from alforria models:

alforria models libertai
alforria -m libertai/<model-id>

If you set model in opencode.json, confirm that the provider id and model id match the catalog, and that the provider is not listed in disabled_providers.

My configuration is ignored

Remember the precedence: the global config is loaded first, then project opencode.json files from the filesystem root down to the working directory, then .opencode directories, then managed config. Later sources win.

  • Run alforria debug config and check the resolved value.
  • Confirm you are editing the file reported by alforria debug paths, or the project file for the directory you started in.
  • OPENCODE_CONFIG, OPENCODE_CONFIG_DIR, OPENCODE_CONFIG_CONTENT, OPENCODE_PERMISSION, and OPENCODE_DISABLE_PROJECT_CONFIG are not honored by the main config loader yet. Put the settings in a config file.
  • Arrays replace the value from an earlier source rather than adding to it. Only instructions entries are combined.
  • JSONC allows comments and trailing commas. A syntax error in a project config file stops the load with an error that names the file. A syntax error in the global config does not: the whole global config is skipped, and the warning only shows in alforria serve --print-logs output.

Login fails

  • For LibertAI, alforria auth login -p libertai opens a browser and a local callback. If the browser runs on another machine, it cannot reach that callback: sign in there and paste the code at the prompt, either the value after code= or the whole redirect URL.
  • For API-key providers, the key is stored by the auth store. If the provider reports an authentication error, log out and log in again: alforria auth logout <provider>.
  • Check that system time is correct. OAuth and signed requests can fail when the clock is far off.

The server returns 401

  • If you set OPENCODE_SERVER_PASSWORD, use that value and the configured username (default alforria).
  • If you did not set it, alforria serve generated a password and printed it once at startup. Restart the server if you lost it. Other commands, such as alforria web, do not generate a password and run without auth.
  • Setting the password to an empty string disables auth and prints a warning. That is an explicit opt-out, not a fix for a 401.
  • alforria attach and alforria run --attach accept -u and -p.

The server is unreachable from another machine

OPENCODE_SERVER_PASSWORD='a-long-secret' \
  alforria serve --hostname 0.0.0.0 --port 4096
  • The default hostname is 127.0.0.1, which only accepts local connections.
  • Open the port in your firewall.
  • Over SSH, forward the port with ssh -L 4096:localhost:4096 user@host and use http://localhost:4096.
  • The server has no TLS. Put it behind a TLS proxy before using an untrusted network.

The web client is blank or cannot connect

  • Confirm the server is running and http://<host>:<port>/ responds.
  • If OPENCODE_DISABLE_EMBEDDED_WEB_UI=1 is set, the server does not serve the UI. Unset it or use a separate client.
  • Behind a reverse proxy, disable response buffering for SSE and forward WebSocket upgrades for PTY connections.
  • Check the browser console and the server logs (alforria serve --print-logs --log-level DEBUG).

Snapshots or revert are unavailable

  • Snapshots require a Git repository. Run git init or start alforria in a checkout.
  • snapshot: false in config disables them for the project.
  • Snapshot and revert are not a backup system. Review the diff before reverting, and keep your own backups.

The bash tool cannot find a shell

The bash tool needs a POSIX shell. On Windows, use WSL or make sure a compatible shell is available. On minimal containers, install a shell and common utilities.

The TUI renders badly

  • Try a different TERM value. A modern terminal with truecolor support gives the intended palette.
  • If mouse handling is the problem, set "mouse": false in tui.json.
  • Delete or rename tui.json to rule out a bad keybind or theme entry. The TUI falls back to defaults. A tui.json that fails to parse or validate is skipped, with a warning in log/tui.log in the data directory.

Collecting logs

alforria serve --print-logs --log-level DEBUG

Logs go to stderr. Only serve prints logs; other commands ignore --print-logs. The TUI writes its warnings to log/tui.log in the data directory (~/.local/share/opencode/log/tui.log by default). Remove API keys, tokens, file contents, and transcript text before sharing logs.

Reset local state

alforria debug paths prints the data and config directories. The SQLite database is opencode.db in the data directory. Back up anything you want to keep before deleting these files.

You can remove the binary from the directory where you installed it. Package manager integration is not built in.

Reporting a problem

  • Bugs and feature requests: github.com/alforria-ai/alforria/issues
  • Security issues: do not post vulnerability details in a public issue. A private reporting channel is not available yet.
  • Include the version, OS, install method, the command you ran, and the relevant logs. Redact secrets first.