Common issues and solutions when working with Seed Hypermedia.
Daemon Issues
Daemon won't start
Check if another instance is running: pgrep -f seed-daemon
Kill existing processes if needed: pkill -f seed-daemon
Port already in use
Default gRPC port is 55002. Check: lsof -i :55002
Headless/server operation
For servers without a display, use: SEED_FILE_KEYSTORE=1 seed-daemon -data-dir ~/.seed-daemon
Key Management
List available keys with the Daemon/ListKeys gRPC call. Keys are stored in the daemon's data directory.
Document Publishing
If documents don't appear on gateway, push directly with PushResourcesToPeer instead of waiting for gossip.
CRITICAL: Block types must be PascalCase! Use Paragraph, Heading, Code - NOT lowercase. Lowercase creates corrupt empty blocks.
Networking
Can't fetch remote docs? Try ForceSync on the resource URL to pull from the network.
Common Errors
• 'document not found' - Document doesn't exist or hasn't synced. Try ForceSync.
• 'key not found' - Signing key unavailable. Check ListKeys.
• 'invalid block type' - Use PascalCase: Paragraph, Heading, Code, Image, Embed.
Debugging Checklist
1. Daemon running? pgrep -f seed-daemon
2. gRPC reachable? grpcurl -plaintext localhost:55002 list
3. Have the key? Check ListKeys
4. Gateway up? curl https://hyper.media/hm/api/config
5. Pushed to gateway? Use PushResourcesToPeer after publishing