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:
Problem: Commands fail with authentication errors.Solution:
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:
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:
2

Approve the device

3

Check runtime logs

On the device, check if the runtime is actually running:
Problem: m87 runtime run fails or exits immediately.Diagnostic steps:
Common causes:
  • Port conflict with another process
  • Firewall blocking outbound connections
  • Missing network connectivity
  • Corrupted configuration file
Solution: Try restarting with verbose logging:
Problem: Runtime service doesn’t start after running m87 runtime enable --now.Solutions:
1

Check service status

2

Check logs

3

Verify binary location

Ensure m87 binary is in your PATH:
4

Reinstall service

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

2

Verify runtime is running

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

Check network stability

Network interruptions can cause connection issues. Restart the runtime:
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:
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:
4

Check port format

Verify correct syntax:

​
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

2

Manual download

Download from releases page and install manually:
3

Verify PATH

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

Check Rust version

m87 requires Rust 1.85+:
2

Clean build

3

Check dependencies

Ensure you have required system dependencies:

​
Docker-Specific Issues

Problem: m87 <device> docker ps returns permission errors.Solutions:
  • Ensure Docker is installed on the device
  • Add user to docker group:
  • Restart runtime after group change:
Problem: m87 <device> deploy succeeds but containers don’t start.Diagnostic steps:

​
Getting More Help

If your issue isn’t covered here:
  1. Enable debug logging:
  2. Check audit logs:
  3. View runtime 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)