Troubleshooting

First: ivralo doctor

ivralo doctor

Doctor checks the environment section by section: the database, the model, the disk, skills, integrations, permissions, the API and more. Each row is ok or fail, and a failed row says its fix on the line under it:

providers
  fail  model endpoint http://gpu-box:8000/v1  does not answer ([Errno 111] Connection refused)
        check --model-url (IVRALO_OPENAI_COMPATIBLE_URL in .env) and that the machine serving the model is up

It ends with Everything checks out. or Some checks failed. and exits 1 when any row failed, so it also works in a script. Fix the failed rows first. See Doctor for every section.

Then: ivralo trace last

Before blaming the model, read what the model actually saw:

ivralo trace last

Every tool call is there with its arguments and output, a failed call carries its code (REFUSED_BY_POLICY, TIMEOUT, NETWORK_BLOCKED, ...), and a failed request to the model has a model row with the status and the provider's answer. See Observability.

The database cannot be reached

Could not reach PostgreSQL at postgresql+psycopg://ivralo:***@127.0.0.1:5432/ivralo

What to do depends on where your database comes from:

IVRALO_PG_HOST defaults to 127.0.0.1, not localhost: Windows resolves localhost to ::1 first, and the container listens on IPv4 only. See PostgreSQL.

The model does not answer

The reply is cut off at the length limit

the model spent its whole output allowance of 8192 tokens (IVRALO_MAX_TOKENS) and wrote no reply

The model reached its output allowance. A thinking model can spend all of it on its reasoning and write nothing. The sentence names the setting that moves it:

• IVRALO_NUM_PREDICT for an Ollama model (8192 by default);
• IVRALO_MAX_TOKENS for every other model (8192 by default).

An incident investigation whose report was cut this way is asked once more, with the allowance doubled when ivralo sets it. If it is cut again, the run ends on this sentence.

The folder is not trusted

A repository's own declarations run commands on your machine, so they wait until a person trusts the folder. Until then the commands under # Commands are refused, no language server starts, the folder's permissions file can only take permissions away, its .ivralo/.env is not read, and git writes are refused. Doctor's environment section says so.

ivralo trust .

Without a terminal (a pipe, a schedule, a server) nobody can be asked, and a folder with no answer counts as not trusted. In a script, ivralo trust --yes . records the yes. ivralo trust --list shows every trusted folder; ivralo trust --revoke . takes it back.

The shell policy refused a command

A call that fails with REFUSED_BY_POLICY is a guardrail working as designed. Which one depends on the verdict:

• deny: recursive deletes, system changes, nested shells, the network (curl, wget), the machine's package managers, any path outside the workspace, and any word naming .env, .ivralo/ or .git/. No setting lifts these.
• ask, with nobody there: a command the policy asks about is refused in ivralo ask in a pipe and in a schedule; a job parks on it instead. To stop it asking, press p in the approval dialog once, or add its prefix to the allow list of .ivralo/permissions.json (for example "allow": ["uv add"]).

See Shell commands and permissions.json.

The port is taken

port 61017 is taken by something that is not ivralo; pass --port or set IVRALO_API_PORT

ivralo serve listens on 127.0.0.1:61017 and exits 1 when the port is in use. If another ivralo serve holds it, the message says so: stop that one, or choose another port with --port or IVRALO_API_PORT. Clients such as ivralo ask --via-api read the same setting.

Other symptoms