This guide helps you diagnose and resolve common issues when building with Mau. For each problem, we provide the symptoms, root cause, and solution.
Symptom:
go: module github.com/mau-network/mau: Get "https://proxy.golang.org/...": dial tcp: lookup proxy.golang.org: no such host
Solution:
1# Set GOPROXY to direct if behind corporate firewall
2export GOPROXY=direct
3
4# Or use a different proxy
5export GOPROXY=https://goproxy.io,direct
Symptom:
package github.com/ProtonMail/go-crypto/openpgp: cannot find package
Solution:
1# Run go mod tidy to resolve dependencies
2go mod tidy
3
4# Verify go.mod is up to date
5go mod verify
Symptom:
mkdir ~/.mau/myaccount: permission denied
Solution:
1# Ensure home directory is writable
2ls -ld ~
3
4# Fix permissions if needed
5chmod 755 ~
6
7# Verify Mau directory is secure (700 recommended)
8chmod 700 ~/.mau
ErrPassphraseRequired ¶Full Error:
Passphrase must be specified
Cause: Attempting to decrypt a private key without providing the passphrase.
Solution:
1// When creating account with passphrase
2account, err := mau.NewAccount("/path/to/account", "my-secure-passphrase")
3
4// Or set passphrase after loading
5err = account.SetPassphrase("my-secure-passphrase")
ErrIncorrectPassphrase ¶Full Error:
Incorrect passphrase
Cause: The provided passphrase doesn’t match the one used to encrypt the private key.
Solution:
ErrNoIdentity ¶Full Error:
Can't find identity
Cause: The PGP keyring doesn’t contain a usable identity (primary key with user ID).
Solution:
1# Verify key has identity
2gpg --list-keys "account-name"
3
4# If missing, create new account
5mau init new-account
ErrAccountAlreadyExists ¶Full Error:
Account already exists
Cause: Trying to initialize an account in a directory that already has account.pgp.
Solution:
1# Use a different directory
2mau init myaccount2
3
4# Or remove existing account (WARNING: destroys keys)
5rm -rf ~/.mau/myaccount
6mau init myaccount
ErrCannotConvertPrivateKey / ErrCannotConvertPublicKey ¶Cause: PGP key format is unsupported or corrupted.
Solution:
1# Export and re-import key to fix format issues
2gpg --export-secret-keys account-email > private.asc
3gpg --export account-email > public.asc
4gpg --delete-secret-and-public-key account-email
5gpg --import private.asc
6gpg --import public.asc
7shred -u private.asc # Securely delete
ErrCantFindFingerprint ¶Full Error:
Can't find fingerprint.
Cause: Trying to look up a peer’s address in Kademlia DHT, but no nodes have announced that fingerprint.
Solutions:
1// Peer must announce to DHT
2client.AnnounceToDHT()
1// Connect directly if you know their address
2err := client.AddFriend(fingerprint, "192.168.1.100:8443")
1// DHT announcements take 5-30 seconds to propagate
2time.Sleep(30 * time.Second)
3addr, err := client.LookupFingerprint(ctx, fingerprint)
ErrCantFindAddress ¶Full Error:
Can't find address (DNSName) in certificate.
Cause: TLS certificate doesn’t contain fingerprint in Subject Alternative Names (SANs).
Solution:
1// Regenerate certificate with proper SANs
2cert, err := client.GenerateCertificate()
3// Mau automatically includes fingerprint in DNSNames
4
5// Verify certificate has correct SANs
6for _, name := range cert.Leaf.DNSNames {
7 fmt.Println("SAN:", name)
8}
ErrServerDoesNotAllowLookUp ¶Full Error:
Server doesn't allow looking up friends on the internet
Cause: The Kademlia resolver is explicitly disabled (privacy mode).
Solution:
1// Enable Kademlia resolver
2resolvers := []Resolver{
3 &KademliaResolver{
4 client: client,
5 },
6}
7
8// Or use mDNS for local network only
9resolvers := []Resolver{
10 &LocalResolver{},
11}
Symptom: Peers can’t connect even with correct address.
Solution:
1# Check if port is open (default 8443)
2sudo ufw status
3sudo ufw allow 8443/tcp
4
5# Verify service is listening
6netstat -tulpn | grep 8443
7
8# Test from another machine
9curl --insecure https://peer-ip:8443/ping
Symptom:
No services found. Please make sure the firewall is not blocking connections.
Cause: Router doesn’t support UPnP, or UPnP is disabled.
Solution:
1# Manual port forwarding:
2# 1. Log into your router's admin panel
3# 2. Navigate to Port Forwarding / NAT
4# 3. Forward external port 8443 → your-local-ip:8443
5
6# Or disable UPnP in Mau and use manual port
7client, err := mau.NewClient(dataDir, mau.WithoutUPnP())
ErrInvalidFileName ¶Full Error:
invalid file name: contains path separators or invalid characters
Cause: File name contains /, \, or other forbidden characters.
Solution:
1// Use safe file names (no path separators)
2filename := "my-post.json" // ✅ Good
3filename := "../etc/passwd" // ❌ Bad
4filename := "dir/file.json" // ❌ Bad
5
6// Sanitize user input
7import "path/filepath"
8filename = filepath.Base(userInput) // Strips directory components
Symptom:
file is not signed
Cause: File was created without a signature, or signature was stripped.
Solution:
1// Always sign files when saving
2err := client.SaveFile(filename, data, mau.WithSigning())
3
4// Verify signature is present
5err := client.VerifyFile(filename)
6if err != nil {
7 log.Println("Warning: file signature invalid")
8}
Cause: File signature doesn’t match the claimed author’s public key.
Possible Reasons:
Solution:
1// Check who signed the file
2signer, err := client.GetFileSigner(filename)
3if err != nil {
4 log.Fatal("Can't determine signer:", err)
5}
6fmt.Println("File signed by:", signer)
7
8// Ensure you have the correct public key
9client.ImportPublicKey(signer, publicKeyData)
Symptom: File downloads but can’t be decrypted.
Cause: File was encrypted for a different recipient.
Solution:
1// Check if file is encrypted for you
2recipients, err := client.GetFileRecipients(filename)
3if !contains(recipients, myFingerprint) {
4 log.Fatal("File not encrypted for you")
5}
6
7// Request sender to re-encrypt for you
Symptom:
listen tcp :8443: bind: address already in use
Cause: Port 8443 is already in use by another process.
Solution:
1# Find process using the port
2sudo lsof -i :8443
3# or
4sudo netstat -tulpn | grep 8443
5
6# Kill the process
7sudo kill -9 <PID>
8
9# Or use a different port
1client, err := mau.NewClient(dataDir, mau.WithPort(9443))
Symptom:
x509: certificate signed by unknown authority
Cause: Mau uses self-signed certificates (by design).
Solution:
1// This is expected behavior in P2P systems
2// Mau verifies fingerprints instead of CA chains
3
4// For testing with curl:
5curl --insecure https://localhost:8443/ping
6
7// In production, fingerprint verification provides security
Symptom: Peer returns 401 when trying to fetch files.
Cause: TLS mutual authentication failed (wrong client certificate).
Solution:
1// Ensure you're using the correct client certificate
2// Mau automatically provides the right cert
3
4// Verify peer has your public key
5err := client.ExportPublicKey()
6// Send publicKey to peer out-of-band
7
8// Verify peer is in your friends list
9friends, _ := client.ListFriends()
10for _, f := range friends {
11 fmt.Println(f.Fingerprint)
12}
ErrIncorrectPeerCertificate ¶Full Error:
Incorrect Peer certificate.
Cause: The peer’s TLS certificate fingerprint doesn’t match their claimed PGP fingerprint.
Solution:
1// Remove stale friend
2client.RemoveFriend(fingerprint)
3
4// Re-add with correct fingerprint
5client.AddFriend(correctFingerprint, address)
Symptom: Files take minutes to sync between peers.
Causes & Solutions:
1// Split large files into chunks
2const chunkSize = 1 << 20 // 1 MB
3for i := 0; i < len(data); i += chunkSize {
4 chunk := data[i:min(i+chunkSize, len(data))]
5 client.SaveFile(fmt.Sprintf("file-part-%d.json", i), chunk)
6}
1// Batch file operations
2files := []string{"post1.json", "post2.json", "post3.json"}
3client.SyncFiles(files) // More efficient than individual syncs
1# Test connection to peer
2ping peer-ip
3traceroute peer-ip
4
5# Use local network discovery (mDNS) when possible
6client.EnableMDNS()
Symptom: Mau process uses excessive RAM.
Solutions:
1client, err := mau.NewClient(dataDir, mau.WithMaxDHTNodes(100))
1// Set connection timeout
2client.SetConnectionTimeout(5 * time.Minute)
1// Instead of loading full file
2data, _ := client.ReadFile("large-video.mp4") // ❌ Loads all into RAM
3
4// Use streaming
5reader, _ := client.OpenFile("large-video.mp4") // ✅ Streams
6defer reader.Close()
7io.Copy(output, reader)
Cause: RSA encryption is CPU-intensive for large files.
Solution:
1// Use symmetric encryption for large files (AES is faster)
2// Mau automatically uses hybrid encryption (RSA for key, AES for data)
3
4// For very large files, compress before encrypting
5import "compress/gzip"
6
7compressed := new(bytes.Buffer)
8gzipWriter := gzip.NewWriter(compressed)
9gzipWriter.Write(largeData)
10gzipWriter.Close()
11
12client.SaveFile("large-file.json.gz", compressed.Bytes())
1import "log"
2
3// Set log level to debug
4log.SetFlags(log.LstdFlags | log.Lshortfile)
5
6// Log all DHT operations
7client.SetLogLevel(mau.LogDebug)
1# Capture Mau traffic
2sudo tcpdump -i any port 8443 -w mau-traffic.pcap
3
4# Analyze with Wireshark
5wireshark mau-traffic.pcap
1# Check PGP key is valid
2gpg --list-keys --keyid-format LONG
3
4# Export and inspect
5gpg --export-options export-minimal --export <key-id> | gpg --list-packets
1# Test if peer is reachable
2curl -v --insecure https://peer-ip:8443/ping
3
4# Check TLS handshake
5openssl s_client -connect peer-ip:8443 -showcerts
1import _ "net/http/pprof"
2import "net/http"
3
4// Start profiler
5go func() {
6 log.Println(http.ListenAndServe("localhost:6060", nil))
7}()
8
9// Access profiles at http://localhost:6060/debug/pprof/
1# Check Mau process status
2ps aux | grep mau
3
4# Monitor resource usage
5htop -p $(pgrep mau)
6
7# Check open files/connections
8lsof -p $(pgrep mau)
9
10# Verify firewall rules
11sudo iptables -L -n | grep 8443
12
13# Test DNS resolution (for Kademlia bootstrap)
14nslookup bootstrap.mau-network.com
If you encounter an issue not covered here:
Check GitHub Issues: mau-network/mau/issues
Search Discussions: mau-network/mau/discussions
File a Bug Report:
go version)uname -a)Security Issues: Email security@mau-network.com (PGP key on website)
Quick lookup table for all Mau errors:
| Error | Module | Description | Common Fix |
|---|---|---|---|
ErrPassphraseRequired |
account | Passphrase not provided | Supply passphrase when creating account |
ErrIncorrectPassphrase |
account | Wrong passphrase | Verify passphrase is correct |
ErrNoIdentity |
account | No PGP identity found | Create new account with mau init |
ErrAccountAlreadyExists |
account | Account already exists in directory | Use different directory or remove existing |
ErrCannotConvertPrivateKey |
account | Private key format unsupported | Re-export key from GPG |
ErrCannotConvertPublicKey |
account | Public key format unsupported | Re-export key from GPG |
ErrFriendNotFollowed |
client | Trying to access unfollowed friend | Add friend with client.AddFriend() |
ErrCantFindFriend |
client | Friend not in local list | Verify fingerprint and re-add |
ErrIncorrectPeerCertificate |
client | TLS cert doesn’t match fingerprint | Verify peer identity, re-add friend |
ErrInvalidFileName |
file | File name has invalid characters | Use safe file names (no / or \) |
ErrCantFindFingerprint |
fingerprint | DHT lookup failed | Ensure peer announced, try direct connect |
ErrCantFindAddress |
fingerprint | Cert missing fingerprint in SANs | Regenerate certificate |
ErrServerDoesNotAllowLookUp |
resolvers | Kademlia disabled | Enable DHT resolver |
Last Updated: March 16, 2026