Common issues and solutions when working with Seed Hypermedia. This guide covers daemon problems, key management, publishing, networking, and debugging strategies.

If the daemon fails to start, check for an existing instance:

# Check if already running
pgrep -f seed-daemon

# Kill existing instance if needed
pkill -f seed-daemon

# Start fresh
seed-daemon -data-dir ~/.seed-daemon

Common causes: another daemon already running, port already in use, corrupted data directory, or insufficient permissions on the data directory.

The daemon uses two ports by default: 55001 for HTTP and 55002 for gRPC. If either is in use, the daemon will fail to start.

# Check what's using the ports
lsof -i :55001
lsof -i :55002

# Use custom ports if needed
seed-daemon -data-dir ~/.seed-daemon -http.port 56001 -grpc.port 56002

On servers without a display, the daemon may fail because it tries to open a UI for key management. Use the file keystore environment variable:

# Enable file-based keystore (no GUI required)
SEED_FILE_KEYSTORE=1 seed-daemon -data-dir /data

# As a systemd service
[Service]
Environment=SEED_FILE_KEYSTORE=1
ExecStart=/usr/local/bin/seed-daemon -data-dir /data

If you don't specify -data-dir, the daemon uses ~/.mtt (the legacy default). This can cause confusion when running multiple instances or on servers.

# Always specify data directory explicitly
seed-daemon -data-dir ~/.seed-daemon

# Check what data directory is in use
ls -la ~/.seed-daemon/
ls -la ~/.mtt/  # Legacy location

If you get a "key not found" error, verify which keys are available on your daemon:

# List all keys on the daemon
grpcurl -plaintext localhost:55002 com.seed.daemon.v1alpha.Daemon/ListKeys

# Or with ion-hm
ion-hm keys list

Key names are case-sensitive. The name you use in CLI commands must exactly match the name shown in ListKeys output.

If you need a new key for publishing, create one through the daemon:

# Create a new key pair
grpcurl -plaintext -d '{"name": "mykey"}' \
  localhost:55002 com.seed.daemon.v1alpha.Daemon/CreateKey

# The response includes your account ID (z6Mk...)
# Save this — it's your permanent identity

Keys are stored in your data directory. If you lose them, you lose access to your account permanently. There is no recovery mechanism.

# Back up your keys (critical!)
cp -r ~/.seed-daemon/keys/ ~/seed-keys-backup/

# Keys are in the data directory under keys/
ls ~/.seed-daemon/keys/

The most common issue: you published locally but didn't push to the gateway. Documents are not automatically synced — you must explicitly push them.

# Push a specific document to the production gateway
ion-hm push hm://z6MkYourAccount.../your-path --recursive

# Or push via raw gRPC
grpcurl -plaintext -d '{
  "addrs": ["/p2p/12D3KooWEDdEeuY3oHCSKtn1eC7tU9qNWjF9bb8sCtHzpuCjvomQ"],
  "resources": ["hm://z6MkYourAccount.../your-path"],
  "recursive": true
}' localhost:55002 com.seed.documents.v3alpha.Resources/PushResourcesToPeer

Don't rely on gossip/discovery to propagate documents — it's slow and unreliable. Always push directly.

If your published document appears empty or malformed, the most common cause is incorrect block structure in JSON:

// ✅ CORRECT: text goes INSIDE block
{"block": {"type": "Paragraph", "text": "Hello world"}, "children": []}

// ❌ WRONG: text as sibling of block (creates empty blocks!)
{"block": {"type": "Paragraph"}, "text": "Hello world", "children": []}

// ❌ WRONG: lowercase block type
{"block": {"type": "paragraph", "text": "Hello"}, "children": []}

Block types must be PascalCase: Paragraph, Heading, Code, Image, Embed, Video, Math, OrderedList, UnorderedList. Lowercase types create structurally valid but empty documents.

Always validate your JSON before publishing to catch these issues early:

# Validate JSON structure
ion-hm validate json /tmp/my-document.json

# Publish with built-in validation (fails if issues found)
ion-hm publish-safe mykey /tmp/my-document.json --url "hm://z6Mk.../path"

# Validate an already-published document
ion-hm validate doc "hm://z6Mk.../path"

# Validate your entire site
ion-hm validate site z6MkYourAccountId

If you can't read documents from other accounts, try forcing a sync from the network:

# Force sync a specific document
grpcurl -plaintext -d '{
  "url": "hm://z6MkRemoteAccount.../path"
}' localhost:55002 com.seed.documents.v3alpha.Resources/ForceSync

# Check daemon connectivity
grpcurl -plaintext localhost:55002 com.seed.daemon.v1alpha.Daemon/GetInfo

If the gateway isn't responding, verify it's running and accessible:

# Check gateway health
curl -s https://hyper.media/hm/api/config | jq .

# Check your own gateway
curl -s http://localhost:55001/hm/api/config | jq .

Note: The gateway returning HTTP 200 doesn't always mean it's healthy — check the response content. A "Not Found" page can still return 200.

If your daemon can't find peers, check that your network allows libp2p connections. Some corporate firewalls block the required ports. You can manually add peers:

# Connect to hyper.media peer directly
grpcurl -plaintext -d '{
  "addrs": ["/dns4/hyper.media/tcp/4001/p2p/12D3KooWEDdEeuY3oHCSKtn1eC7tU9qNWjF9bb8sCtHzpuCjvomQ"]
}' localhost:55002 com.seed.networking.v1alpha.Networking/Connect

When something isn't working, run through this checklist in order:

1. Is the daemon running?

pgrep -f seed-daemon

2. Can you reach gRPC?

grpcurl -plaintext localhost:55002 list

3. Do you have the right key?

grpcurl -plaintext localhost:55002 com.seed.daemon.v1alpha.Daemon/ListKeys

4. Has the document been pushed to gateway?

ion-hm push hm://z6MkYourAccount.../path --recursive

5. Can you read it back from the gateway?

curl -s https://hyper.media/hm/z6MkYourAccount.../path | head -20

If you're still stuck after this checklist, the Seed Hypermedia community can help. File issues on GitHub or reach out through the desktop app's feedback mechanism.