Skip to content

Troubleshooting Guide

Diagnose and fix common Kunuleco issues.

Commands here are node verbs unless marked otherwise. Type them as shown over SSH, or in the Urchin client's command mode (add / in chat mode). Commands that start with / exist only in the client.

Quick Diagnostics

transport
@node_processes
@netcheck
@version

transport shows each transport's state. @node_processes shows which daemons are running. @netcheck checks the network for peer-to-peer compatibility. @version shows the node's build and commit.

The node's logs are in its logs directory, ~/.local/share/kunuleco/logs/ on an installed Linux node and %LOCALAPPDATA%\Kunuleco\logs\ on Windows. Start with node.log. The daemons each have their own log beside it. The logs can contain NUL bytes, so search them with grep -a:

grep -a -i error ~/.local/share/kunuleco/logs/node.log

Installation Issues

Setup Wizard Stalls or Fails to Download

Solutions:

  1. Check your internet connection
  2. Some networks block peer-to-peer traffic. Try a phone hotspot or a different network
  3. Close Urchin and launch it again. Setup resumes where it left off

Missing .pck File on Launch

On Linux and Windows, the executable and urchin.pck must be in the same folder. Move them together and launch again. On macOS the content package is inside Urchin.app.

Broken or Incomplete Installation

In the Urchin client:

/check-updates
/update
/reinstall

/check-updates shows which components have updates. /update installs them, and /update client updates only the client. /reinstall performs a clean reinstall of every component.

The Installer's Command Line

The installer that the setup wizard uses also has a command line. Run it with the node's Python, which is in the installation's venv directory:

# Linux
~/.local/share/kunuleco/venv/bin/python3 -m kunuleco_installer health

On Windows the Python is %LOCALAPPDATA%\Kunuleco\venv\Scripts\python.exe. Its commands are install, health, update, repair, rollback, info and uninstall.

  • health checks the installed IPFS, Tor and Veilid. --component <ipfs|tor|veilid> checks one, and --json prints JSON.
  • repair diagnoses and repairs problems. --diagnose-only reports without changing anything, --auto fixes the safe ones, and --component <name> limits it to one component.
  • info shows the installed components, versions and paths.

Startup Issues

A Daemon Did Not Start

Symptoms: One of these lines in node.log:

  • [WARN] IPFS not available - some features will be limited
  • [WARN] Tor not available - onion services disabled
  • [WARN] Veilid not available - cross-internet P2P limited

The node keeps running without that daemon.

Solutions:

  1. Check that daemon's own log (ipfs-daemon.log, tor-daemon.log or veilid-daemon.log)
  2. Restart Urchin, which restarts the node and its daemons
  3. Run the installer's repair --component <ipfs|tor|veilid>

Another Node Is Already Running

Cause: A second node process started on the same data directory or the same ports.

Solutions:

# Find the running node
ps aux | grep kunuleco

Close the other process, then start Urchin again.

Can't Sign In

Solutions:

  1. Check the password (caps lock, typing errors)
  2. After repeated failures the node answers Too many failed attempts. Try again in <N>s. The lockout decays. One failure is forgiven for every 300 seconds without another
  3. There is no password reset. If you have an exported identity, restore it with import-identity. See Identity Management

Connection Issues

mDNS Not Discovering Peers

Symptoms: Local peers not visible.

Diagnosis:

@discover
@peers

Solutions:

  1. Verify you are on the same network (ping the other machine)
  2. Check the firewall allows UDP 5353
  3. Check the firewall allows TCP 4243 (the CapTP port)
  4. On some routers, "AP isolation" blocks mDNS. Turn it off
  5. Check both nodes run the same version. A newer node can dial an older one over mDNS, but an older node cannot dial a newer one

Veilid Not Connecting

Symptoms: A Veilid verb answers Veilid not available, or connections time out.

Diagnosis:

transport
@veilidstatus

Solutions:

  1. Wait for Veilid to attach to its network, which takes longer on the first start
  2. Check the system time is accurate. Veilid requires it
  3. Check veilid-daemon.log
  4. Try /update in the Urchin client

Time sync fix:

# Linux
sudo timedatectl set-ntp true

# macOS
sudo sntp -sS time.apple.com

Tor Not Connecting

Symptoms: @torstatus answers Tor not available (is tor running?), or circuits fail.

Diagnosis:

@torstatus
@node_processes

# Check the node's Tor control port answers
nc -z localhost 19051

Solutions:

  1. Check tor-daemon.log
  2. Restart Urchin, which restarts the node's Tor
  3. The network may be blocking Tor

Peer Disconnects Immediately

Symptoms: A connection opens, then drops.

Possible causes:

  • The two nodes run different versions
  • The peer's signed hello was refused. A refused Tor hello closes the connection, and the node stops re-dialling a peer it refused until you dial it yourself
  • One of you has blocked the other
  • An unstable transport

Solutions:

  1. Update both nodes to the same version
  2. Check node.log for errors
  3. Run ping <name> to see which transports reach the peer

Performance Issues

High Latency

Symptoms: Messages take seconds to deliver.

Diagnosis:

ping mira#4Q7K2M

ping shows which transports reach the peer. A peer on the same LAN should be reached over mDNS.

High Memory or CPU Use

Possible causes:

  • The current IPFS version has a known memory growth issue
  • Many active connections

Solutions:

  1. Restart Urchin, which clears the IPFS memory growth
  2. Check IPFS with @ipfspeers
  3. Report it with bug <description> if it persists

Data Recovery

Roll Back an Update

Before an update, the installer backs up the components it replaces. It backs up installed software, not your identity or places.

~/.local/share/kunuleco/venv/bin/python3 -m kunuleco_installer rollback --list
~/.local/share/kunuleco/venv/bin/python3 -m kunuleco_installer rollback --backup-id <backup_id>

Start Fresh

Run /reinstall in the Urchin client first. It reinstalls every component.

If Urchin will not launch at all, delete the Kunuleco directory and launch Urchin again, and setup runs from the start:

  • Windows: %LOCALAPPDATA%\Kunuleco
  • Linux: ~/.local/share/kunuleco

Warning: Deleting that directory deletes your identity and everything on the node. Export your identity first.

The installer's uninstall removes the components and keeps identity keys unless you add --force. --dry-run shows what it would delete.

Export Before a Reset

export-identity '<path>' <base64_passphrase>

See Identity Management. There is no command to export places, capsules or objects.

Getting Help

Collect Diagnostic Info

bug <description>

bug saves a snapshot of the node's state as a local JSON file in a bugs/ folder under the node's data directory. It sends nothing. In the Urchin client, /bug <description> saves the client's side as well. Zip the files, add the node's logs, and send them by hand.

Report an Issue

  1. Collect diagnostics (above)
  2. Describe what you were doing
  3. Include error messages
  4. Email alpha@kunul.eco

Common Error Messages

Error Meaning Solution
Too many failed attempts. Try again in <N>s. Repeated failed sign-ins Wait, then check the password
Session expired before sign-in. Reconnect to continue. The connection sat too long before signing in Reconnect (/reconnect in the client)
This is the node's own account. It cannot be signed into. You tried to sign in as the node user Sign in with a person's account
Veilid not available (is veilid-server running?) The node's Veilid is not running Check @node_processes and veilid-daemon.log
Tor not available (is tor running?) The node's Tor is not running Check @node_processes and tor-daemon.log
Invite code '<code>' not found or expired The short code no longer resolves Ask for the join <handle> <presence> form
Error: the host of <presence> refused the join. The host refused you, for example because the presence is invite-only Ask the owner to invite you with door
Only the owner of '<presence>' can change its door. You don't own that presence Ask its owner
Can't block '<name>' yet: this node has never verified who that is, it has only dialled them. Nothing was blocked. No signed hello from that person yet Try again after they connect
Capability denied for <method>: reference revoked Your access was revoked Ask the capsule's owner