Documentation / 04

Troubleshooting

Start with the process, then the local browser, then the network boundary.

Another device cannot connect

  1. Confirm the server is running and note the port in its log.
  2. Open http://localhost:9090 on the host itself.
  3. Find the host's LAN address and open http://LAN-IP:9090 from the other device.
  4. Allow inbound TCP traffic for that port in the host firewall.
  5. Confirm both devices can route to each other; guest Wi-Fi often isolates clients.

When -ssl is enabled, use https://. Its default port becomes 443 unless -port was explicitly supplied.

Uploads or ZIP downloads report permission errors

The process needs read access to shared files, write access for uploads and mutations, and write access to the operating system temporary directory for ZIP creation.

Docker bind mounts

The project image runs as UID/GID 65532. Grant that identity appropriate access to the host directory, or run the container in read-only mode with readable files.

sudo chown -R 65532:65532 /srv/share

Choose permissions that match your host's ownership model; do not make a sensitive directory world-writable just to bypass the error.

Large uploads stop early

Check -max-upload-size, reverse-proxy limits, tunnel limits, available disk space, and request timeouts. For slow large transfers, increase or disable the overall read and write timeouts:

upgopher -read-timeout 0 -write-timeout 0

Upgopher does not implement resumable uploads. An interrupted upload must be restarted.

The browser warns about the certificate

This is expected when using -ssl without -cert and -key. The generated certificate is self-signed. For trusted access, provide a certificate trusted by your devices or terminate TLS at a reverse proxy.

The login prompt repeats

Confirm both -user and -pass are present, credentials are entered exactly, and a reverse proxy is forwarding the Authorization header. Try a private browser window after changing credentials to avoid cached Basic Auth state.

Collect diagnostics

upgopher -h
go version
uname -a   # macOS or Linux

When opening an issue, include the Upgopher version, operating system and architecture, exact command with passwords removed, expected behavior, and sanitized logs. Never publish credentials or absolute paths containing private information.