Vigile
SearchContents

Documentation

Troubleshooting

Start with the doctor. It checks the config file, the data and the running service, changes nothing, and says what to do about each thing it finds.

The doctor

vigile doctor

The commands here are typed in a terminal that is set up as Install and first run leaves it, with the instance running. The doctor also works on an instance that is not running, and says so.

  vigile doctor

  Config
  ✓ config file passes the check          /home/you/vigile/main/config.toml
  ✓ config file is private                readable by its owner only
  ✓ environment overrides are known       no stray VIGILE_ variables
  ✓ listen address is on this machine     127.0.0.1

  Data
  ✓ data folder is writable               /home/you/vigile/main/data
  ✓ disk has free space                   9.2 GB free
  ✓ store "default" can be written        /home/you/vigile/main/data/default.sqlite
  ✓ store "default" is intact             format 2, revision 5
  ✓ automatic backups are on              every 24 hours into /home/you/vigile/main/backups, the newest 30 of a tenant are kept; none taken yet, the first is due when the service runs

  Service
  ✓ service is running                    main 0.1.0, up 6s, process 4242
  ✓ admin key works
  ✓ port belongs to this instance         http://127.0.0.1:8700
  ✓ service holds the data folder         process 4242
  ✓ service runs the code on disk         started after the last change
  ✓ running settings match the config     no restart needed
  ✓ last automatic backup worked          none taken yet; the first is due 2026-01-13T09:14:03.120Z
  ✓ graph is consistent                   1 project, 3 tasks, 3 users, 6 links
  ✓ status timelines are consistent       each project and task has a timeline that ends with its status
  ✓ config users exist                    1 user with a key
  ✓ MCP endpoint answers                  http://127.0.0.1:8700/mcp lists 21 tools
  ✓ web page answers                      http://127.0.0.1:8700/
  ⚠ auth is off for non-admin users       no key needed to act as agent1
    → To require a key from everyone: vigile config set auth.keyless_user ""

  21 passed · 1 warning

It ends with an error when a check fails, so a script can go by it; --json gives the checks as JSON. A warning is not a failure.

What the checks mean

CheckWhen it is not passed
config file passes the checkThe file has a setting that is none, a value of the wrong kind, no admin key. The line says what; fix it with vigile config set
config file is privateOther accounts can read the keys in it. The line gives the command that closes it
environment overrides are knownA VIGILE_ variable matches no setting, usually a typo. It is ignored
listen address is on this machineThe service could not listen there. The line lists the addresses this machine has
data folder is writable, store can be writtenThe account that runs Vigile may not write there. Until it may, every change fails
disk has free spaceLess than 100 MB are free. Writes fail when the disk is full
store is intactThe data file is damaged, or of a format newer than this version understands. Stop the service and restore a backup
no restore is left half-doneA restore was interrupted. Start the service, or run the restore again: either puts the data in order
service is runningNothing of this config answers. Start it with vigile serve
admin key worksThe service refuses the key in the config. vigile user reset-key admin issues a new one
port belongs to this instanceSomething else answers at the config's address
service holds the data folderThe process that answers is not the one that has the data
service runs the code on diskThe code was built after the service started. Restart it
running settings match the configThe config changed since the start. Restart the service for the change to apply
status timelines are consistentA stored status timeline is damaged: it does not end with the status its item has. Restore from a backup
graph is consistentThe data has damage: a record that cannot be read, a link that leads nowhere. This is not about problems in the plan
config users exist, each key is its user's ownThe config has a key for a user that does not exist, or one that was not issued for its user. Such a key lets nobody in
MCP endpoint answers, web page answersThe service runs and one of its parts does not answer. Look at its log
auth is off for non-admin usersA warning, not a failure: connections without a key are let in. See Security

The log

serve writes operations to its output, one line each: the operation, the caller, whether it reads or writes, how long it took and how it ended.

2026-01-12T09:14:03.120Z op=set_task_status caller=agent1 kind=write ms=6.1 result=ok
2026-01-12T09:14:07.482Z op=set_task_status caller=agent2 kind=write ms=0.6 result=rule_violation rule=unfinished_dependencies
  • result is ok or the code of the error; rule names the rule that refused a change.
  • With log_level at info, reads that succeed are left out. debug writes them too; quiet writes no lines for operations.
  • What goes wrong inside the service is written at every level, with where it was thrown.
  • Titles, descriptions and keys are never logged.

Vigile does not keep the log: send the output of serve wherever you keep logs.

When a command cannot reach its service

The command saysIt meansDo
No Vigile service answers at the addressnot_running: no service of this config is running. Nothing was sentStart it: vigile serve
Something else answers therenot_this_service: another program has the port, or a service of another instance. Nothing was sent to itStop that program, or give this instance another port
The service runs at another address, or is not listening yetnot_running: a process holds the data folder and nothing answers at the config's addressWait a moment, or check whether the service was started with other settings than the config's
No config file givenusagePass --config <file>, or set VIGILE_CONFIG
The config is not correctconfig_invalid, with each thing that is wrongFix them with vigile config set

When a command gets no answer

A command ends with the code no_answer, and the exit code 2, when the service took the connection and its answer did not come: within 15 seconds, or because the connection ended first.

A change that was sent may then have been stored, or may be stored yet: the service carries out a request it has taken even after the connection has ended. So do not send it again straight away. First:

  1. Look: vigile get <id> --history shows an item with the changes recorded in its history. A link, also one that gives a task to a user, is looked for in the history of the task.
  2. Wait until the request is over: when the service's log has the line of its operation, or when the service has been stopped and started again.

Only then decide whether to send it again, knowing this:

  • A change that names its item by an ID together with a version is stored only once, however often it is sent: of two such requests, the one that is carried out later is refused with a conflict.
  • A request that takes no version is not held back by one. Creating a task or a project makes another each time it is carried out, and resetting a key replaces the key each time; a link that is there, or an item that is restored, is not made twice. Which operations take a version says it of each. Do not send such a request again while an earlier one may still be outstanding.
  • A request that names a user by its username acts on whoever has the name when it is carried out. Name the user by its ID to be sure.

The service does not start

serve ends with exit code 1 and says why. Its code is cannot_start; for data of a format newer than this version understands it is failed. A start goes through four steps, and a start that failed has done the steps before the one that failed. So a failed start does not by itself mean that the data folder is as it was:

StepItFails with cannot_start whenBy then
1Takes the data folder for itself.Another service, a restore or a command holds the folder, or the folder cannot be written.Nothing in the folder has been changed.
2Puts a restore that was interrupted in order.A backup of the folder is being taken, so the restore cannot be put in order yet.Nothing more than in the step before.
3Opens the plan. A folder that is new gets its data file and the three built-in users.The setting auth.keyless_user names a user that does not exist.An interrupted restore has been put in order, a new folder has its data file, and data that an earlier version wrote has been brought to the present format.
4Listens on the address and port.The port is taken, or the machine has no such address.The same: the restore is in order, a new folder has its data file with the built-in users, and data of an earlier format has been brought to the present one.

Before starting it again, look: vigile doctor checks the config and the data, and says whether a restore was left half-done; what serve said tells which step failed.

It saysDo
The port is already in useStop what is using it, or choose another: vigile config set listen.port <port>
Another Vigile service is already using the data folderStop that service, or point this one at another data_dir. One service per folder
This machine has no such addressCheck listen.address
The config names a user that does not existSet auth.keyless_user to a user that exists, or to nothing
Vigile needs Node.js 22.13 or laterRun it with a newer Node.js

The page

  • The page does not update by itself. That is the default, so that it does not change while you read. Turn on "Auto-refresh" in its settings.
  • The page asks for a key. The instance requires one from everyone. Give it the key of a user; it is kept in that browser.
  • The page says it lost the service. It keeps what it had on screen and finds the service again by itself once it answers.
  • History opens with filters already set. The browser remembers the filters applied last. "Clear" empties and forgets them.
  • The graph is not drawn. A graph of more than 300 items is drawn when asked for: press "Draw the graph".