IPFS Troubleshooting

Common issues with IPFS/Kubo nodes and step-by-step fixes.

Node won't start — 'lock' file error

If you see Error: cannot acquire lock, another IPFS process is already running (or crashed without cleanup).

Fix

# Check for existing processes
ps aux | grep ipfs

# Kill stale processes
killall ipfs

# Remove stale lock file if needed
rm ~/.ipfs/repo.lock

# Restart
ipfs daemon

Zero peers — node can't connect to the network

Possible causes:

Firewall blocking port 4001 — This is the swarm port. It must be open for both TCP and UDP.
ISP blocking P2P traffic — Some ISPs throttle or block P2P connections.
NAT traversal failure — Most home routers need UPnP or manual port forwarding.

Diagnose

# Check listening ports
ss -tlnp | grep 4001

# Check if you can reach bootstrap nodes
ipfs swarm peers

# Test external connectivity (from another machine)
nc -zv YOUR_IP 4001

# Enable relay (helps behind strict NAT)
ipfs config --json Swarm.EnableRelayHop true
ipfs config --json Swarm.RelayClient.Enabled true

Router port forwarding

# Forward these ports in your router admin panel:
# TCP 4001 → your machine's local IP
# UDP 4001 → your machine's local IP
# 
# Or enable UPnP in router settings (easier but less secure)

Pinning is extremely slow or hangs

Large pins (multi-GB) can take a long time. If it seems stuck:

Diagnose & fix

# Check pin progress (use --progress flag)
ipfs pin add --progress <CID>

# If stuck, check if the content is available
ipfs dht findprovs <CID> | head

# If no providers found, the content may be offline
# Wait and retry — providers may come back

# For slow downloads, try adding more bootstrap peers
ipfs bootstrap add /dnsaddr/bootstrap.libp2p.io/p2p/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN

# Restart daemon and retry
ipfs shutdown
ipfs daemon &
ipfs pin add --progress <CID>

CORS errors when accessing the API

If you get CORS errors from a browser-based app (like the Rev Now admin panel):

Fix

# Configure CORS headers
ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["http://localhost:3000", "http://127.0.0.1:3000"]'
ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "POST", "GET"]'
ipfs config --json API.HTTPHeaders.Access-Control-Allow-Headers '["Authorization"]'
ipfs config --json API.HTTPHeaders.Access-Control-Expose-Headers '["Location"]'
ipfs config --json API.HTTPHeaders.Access-Control-Allow-Credentials '["true"]'

# Restart daemon
ipfs shutdown && ipfs daemon

High CPU / memory usage

IPFS can be resource-hungry, especially on first sync or with many pins.

Optimize for low-resource machines

# Reduce connection limits
ipfs config --json Swarm.ConnMgr.LowWater 50
ipfs config --json Swarm.ConnMgr.HighWater 200
ipfs config --json Swarm.ConnMgr.GracePeriod '"30s"'

# Disable unnecessary features
ipfs config --json Discovery.MDNS.Enabled false

# Set storage limit (prevents disk from filling up)
ipfs config --json Datastore.StorageMax '"10GB"'

# Run garbage collection
ipfs repo gc

Content not found on public gateways after pinning

You pinned the content but ipfs.io/ipfs/<CID>shows 504 or "not found":

Your node isn't publicly reachable. Gateways need to fetch from you. Ensure port 4001 is open.
DHT propagation takes time. It can take 5-30 minutes for the network to learn about your content.
Gateway caching. Try a different gateway or add ?nocache=1 to the URL.

Force provide

# Announce to the DHT that you have this content
ipfs dht provide <CID>

# Check your node's public address
ipfs id | grep Addr

# Verify connectivity from outside
# Use https://check.ipfs.network/ to test your node

'ipfs: command not found' after installation

The binary isn't in your PATH.

Fix

# Check where it was installed
which ipfs || find / -name "ipfs" -type f 2>/dev/null

# Common locations
ls -la /usr/local/bin/ipfs

# If installed in a non-standard location, add to PATH
echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.bashrc
source ~/.bashrc

Repository migration needed after Kubo update

After updating Kubo, you may see Error: ipfs repo needs migration.

Fix

# Install the migration tool
go install github.com/ipfs/fs-repo-migrations@latest

# Or download pre-built
wget https://dist.ipfs.tech/fs-repo-migrations/v1.7.1/fs-repo-migrations_v1.7.1_linux-amd64.tar.gz
tar -xvzf fs-repo-migrations_v1.7.1_linux-amd64.tar.gz

# Run migration
fs-repo-migrations -y

# Restart daemon
ipfs daemon

IPFS Setup Guide

Full installation walkthrough →

← All Troubleshooting

Nostr, Tor, Arweave guides