Startup

Common issues starting Valdr with valdr / valdr ui, or when a tool host launches valdr pm.

Port already in use

Symptom: valdr --port 7777 exits with an error that the port is already bound.

Likely cause: Another process, often an older Valdr instance, is already using that port.

Fix:

# Find what is using the port
lsof -i :7777

# Stop the old process if appropriate
kill <PID>

# Or start on a different port
valdr --pm-home ~/.valdr/pm --port 7778

Encrypted startup requires VALDR_DB_USERNAME and VALDR_DB_PASSWORD in non-interactive mode

Symptom: Starting Valdr from an MCP host, script, or other non-interactive process exits immediately with that error.

Likely cause: There is no TTY available, so Valdr cannot prompt for the local database credentials it normally asks for at startup.

Fix: Set both values in the environment that launches Valdr or your MCP host:

export VALDR_DB_USERNAME="yourname"
export VALDR_DB_PASSWORD="yourpassword"

Then restart the process that launches valdr or valdr pm.

An existing --pm-home will not open with your current password

Symptom: A data directory that used to work no longer opens with the credentials you are entering now.

Likely cause: That pm-home is protected by the password you originally used for it.

Fix: Use the original password for that data directory. If you want a fresh start instead, point Valdr at a new --pm-home and configure it again:

valdr --pm-home ~/.valdr/pm-fresh --port 7777

Can’t reach Valdr from another machine

Symptom: Valdr works on the local machine but is unreachable from another device on your network.

Likely cause: The UI binds to 127.0.0.1. Host overrides are ignored.

Fix: Open Valdr on the same machine where it is running, or use an explicit tunnel if you need remote access.

Which --pm-home am I using?

Symptom: You are not sure where Valdr is storing data, or you think you might be looking at the wrong database.

Fix: Check System Monitoring in the running UI. The Process details panel shows the exact PM DB Path.

Global vs repo-local data directory

Symptom: You started Valdr in a different directory and your projects or sessions do not look the way you expected.

Likely cause: You previously used a repo-local --pm-home like ./.valdr/pm, but now you are launching from a different directory.

Fix: Use the same --pm-home consistently. For most workflows, a global path is simpler:

valdr --pm-home ~/.valdr/pm --port 7777

See Install Valdr > Choosing a data directory for the trade-offs.

Related

• Install Valdr > Start Valdr
• System Monitoring