Skip to main content
This guide covers common issues you may encounter when using m87 and their solutions.

​
Authentication Issues

Problem: Running m87 login doesn’t open a browser window.Solutions:
1

Check if browser is available

Ensure you have a default browser configured on your system.
2

Manual authentication

If the browser doesn’t open automatically, copy the URL from the terminal and paste it into your browser manually.
3

Environment variables

Check if BROWSER environment variable is set correctly:
echo $BROWSER
Problem: Commands fail with authentication errors.Solution:
m87 logout
m87 login
This clears expired credentials and re-authenticates with the platform.
Problem: Error message: “No credentials found”Solution: Credentials are stored in ~/.config/m87/. If this directory is missing or corrupted:
m87 login
On Linux, ensure ~/.config directory has proper permissions (755 or 700).

​
Runtime Issues

Problem: Device registered but never shows as “online”.Solutions:
1

Check approval status

List pending devices from your workstation:
m87 devices list
2

Approve the device

m87 devices approve <device-name-or-request-id>
3

Check runtime logs

On the device, check if the runtime is actually running:
m87 runtime status
Problem: m87 runtime run fails or exits immediately.Diagnostic steps:
# Check if another instance is running
ps aux | grep m87

# Check system logs
journalctl -u m87-runtime -n 50

# Verify network connectivity
ping make87.com
Common causes:
  • Port conflict with another process
  • Firewall blocking outbound connections
  • Missing network connectivity
  • Corrupted configuration file
Solution: Try restarting with verbose logging:
RUST_LOG=debug m87 runtime run
Problem: Runtime service doesn’t start after running m87 runtime enable --now.Solutions:
1

Check service status

m87 runtime status
# Or use systemd directly
systemctl --user status m87-runtime
2

Check logs

journalctl --user -u m87-runtime -n 100 --no-pager
3

Verify binary location

Ensure m87 binary is in your PATH:
which m87
4

Reinstall service

m87 runtime disable
m87 runtime enable --now
The runtime service runs as your user (not root). Ensure your user has necessary permissions.

​
Connection Issues

Problem: Device appears in device list but m87 <device> shell or other commands timeout.Solutions:
1

Check device status

m87 <device> status
2

Verify runtime is running

Use another access method (physical access, serial, etc.) to check:
m87 runtime status
3

Check network stability

Network interruptions can cause connection issues. Restart the runtime:
m87 <device> exec -- 'm87 runtime restart'
Problem: Shell sessions drop unexpectedly.Possible causes:
  • Unstable network connection on the device
  • Device going to sleep or low-power mode
  • High network latency
Solutions:
  • Check device network stability
  • Disable power management features that suspend network interfaces
  • Use m87 <device> exec for non-interactive commands instead
Problem: m87 <device> forward command succeeds but port isn’t accessible.Solutions:
1

Verify service is listening

On the device, check if the service is running:
m87 <device> exec -- 'netstat -tulpn | grep <port>'
2

Check bind address

Ensure the service binds to 0.0.0.0 or 127.0.0.1, not a specific IP.
3

Test local connectivity

Try connecting locally on your workstation:
curl http://localhost:<local-port>
4

Check port format

Verify correct syntax:
m87 <device> forward 8080         # localhost:8080 → device:8080
m87 <device> forward 3000:8080    # localhost:3000 → device:8080

​
Platform-Specific Issues

Problem: Runtime commands fail on macOS.Explanation:
The m87 runtime (on-device daemon) only runs on Linux. macOS supports the CLI only.
Supported:
  • m87 login, m87 logout
  • m87 devices list, m87 devices approve
  • m87 <device> shell, m87 <device> exec
  • All device management commands
Not supported on macOS:
  • m87 runtime run
  • m87 runtime enable/start/stop
Problem: Permission errors when running runtime commands.Solutions:
  • Runtime service uses sudo for systemd operations automatically
  • Binary should be executable: chmod +x ~/.local/bin/m87
  • Config directory permissions: chmod 700 ~/.config/m87
Don’t run the runtime itself as root. The service runs as your user account.

​
Build and Installation Issues

Problem: curl -fsSL https://get.make87.com | sh fails.Solutions:
1

Check network connectivity

curl -I https://get.make87.com
2

Manual download

Download from releases page and install manually:
wget https://github.com/make87/m87/releases/latest/download/m87-linux-amd64
chmod +x m87-linux-amd64
mv m87-linux-amd64 ~/.local/bin/m87
3

Verify PATH

Ensure ~/.local/bin is in your PATH:
echo $PATH | grep ".local/bin"
Problem: Building from source fails with compilation errors.Solutions:
1

Check Rust version

m87 requires Rust 1.85+:
rustc --version
rustup update
2

Clean build

cargo clean
cargo build --release
3

Check dependencies

Ensure you have required system dependencies:
# Debian/Ubuntu
sudo apt-get install build-essential pkg-config libssl-dev

# Fedora/RHEL
sudo dnf install gcc pkg-config openssl-devel

​
Docker-Specific Issues

Problem: m87 <device> docker ps returns permission errors.Solutions:
  • Ensure Docker is installed on the device
  • Add user to docker group: 
    m87 <device> exec -- 'sudo usermod -aG docker $USER'
  • Restart runtime after group change: 
    m87 <device> exec -- 'm87 runtime restart'
Problem: m87 <device> deploy succeeds but containers don’t start.Diagnostic steps:
# Check deployment status
m87 <device> deployment status --logs

# Check Docker logs
m87 <device> docker logs <container-name>

# Verify compose file syntax
m87 <device> deployment show --yaml

​
Getting More Help

If your issue isn’t covered here:
  1. Enable debug logging: 
    RUST_LOG=debug m87 <command>
  2. Check audit logs: 
    m87 <device> audit --details
  3. View runtime logs: 
    m87 <device> logs
  4. Report issues: File a bug report at github.com/make87/m87/issues
When reporting issues, include:
  • m87 version (m87 --version)
  • Operating system and architecture
  • Full error message
  • Debug logs (with sensitive data redacted)