Troubleshooting

First identify which layer failed: the local server, the provider connection, a model response, a tool, or computer access. Reinstalling everything can hide the original cause and risks losing useful configuration. Start with the narrowest check below.

The local page does not open

Return to the directory where ABot is installed and run npx abot start. Read the address and error output in that terminal. The default address is http://127.0.0.1:5177, and the terminal process must remain running.

Check your Node.js version with node --version: the package supports ^20.19.0 or >=22.12.0, not Node 21. If a port is already occupied, identify the process that owns it before stopping anything. Do not launch several copies simply because the first browser tab is stale.

The default UI binds to loopback. A phone’s 127.0.0.1 is the phone, not your ABot computer; container and remote deployment access require their own network setup.

The UI opens, but a model request fails

Check the selected model profile and the error reported in the conversation. A working Web UI does not establish a working model connection.

For Ollama, verify the configured endpoint and installed model:

curl http://127.0.0.1:11434/api/tags

Run the check from the environment where the Runtime runs, replacing the address when necessary. Confirm that the response lists the exact model ID in the profile. If it is missing, download that model using ollama pull <model-id> on the Ollama host.

For OpenAI, confirm the provider connection has a valid API key and the requested model is available to the account. Complete the missing-key setup flow if shown. Do not paste keys into model JSON, issue reports, or screenshots. Provider configuration references the environment variable name, for example:

{
  "type": "openai",
  "apiKeyEnv": "OPENAI_API_KEY"
}

This is a provider fragment, not a complete configuration. Review the provider’s actual error before changing route or calibration settings.

A tool is missing or an action waits

Check that the plugin and individual tool are enabled globally and not blocked for the selected model. Permission mode cannot restore a tool that is unavailable.

In Ask and Full, sensitive actions wait for approval of the exact prepared operation. Review the target, command, and working directory rather than granting broader permission just to dismiss the prompt. OS permission failures remain possible after ABot approval.

If a command returns successfully but the desired result is absent, inspect the outcome directly. An exit code does not prove that a visible application opened or a file contains the intended content.

Memory does not enable

The embedding provider must already exist and the selected embedding model must be available from that endpoint. These commands inspect status and discover available models:

npx abot memory status
npx abot memory models --provider <provider-id>

OpenAI model discovery may be unsupported; enter its embedding model ID manually. Enablement performs a real probe and writes configuration only when that probe and validation pass. Restart ABot after CLI enablement or disablement. See memory before enabling it simply to troubleshoot an unrelated chat failure.

A Marketplace link opens ABot but goes no further on Mac

First update and restart the Runtime. A paired Mac can still have an older managed Companion or installation-link handler. Use Repair Mac connection if offered. Otherwise, from the updated project directory:

npx --no-install abot host status
npx --no-install abot host connect --url '<url from host status>'

Replace the placeholder with the exact saved URL returned by host status. This refreshes the managed connection while reusing its pairing and briefly reconnects Computer access. Do not disconnect first. Retry the Marketplace link: it should open plugin review, not install without confirmation.

Collect useful evidence

Record the installed package version with npm ls @abot-ai/runtime, the selected provider and model ID, the route, and a minimal request that reproduces the issue. Include the exact error and whether it happens in a new conversation.

The default model gateway log is .runtime/shared/logs/model-gateway.jsonl; MODEL_GATEWAY_TRACE_FILE can override it. Logs and request traces can include sensitive content. Review and redact them before sharing, and never include .env, credentials, private documents, or pairing invitations in a public report.