Troubleshooting Mach5 One

This guide lists common first-run problems and the information needed for useful issue reports.

Release download problems

Use the official GitHub Releases page:

https://github.com/mach5-io/mach5-one/releases/latest

Do not download Mach5 One binaries from unofficial locations.

Binary will not run

Check:

mach5-one version
command -v mach5-one

Common causes:

• Wrong OS/architecture asset
• Missing executable bit on macOS/Linux
• Archive not fully extracted
• Binary not on PATH
• Platform security quarantine or signing prompt

Collect:

• Asset name
• Checksum result
• OS and architecture
• Error output

Config was not created

Run:

mach5-one init

Default config path:

~/.mach5-one/mach5-one.toml

Use a custom config path:

mach5-one --config ./mach5-one.toml init

Server will not start

Try:

mach5-one start

Common causes:

• HTTP port already in use
• PostgreSQL port already in use
• Data directory permission issue
• Existing Mach5 One process already running
• Unsupported OS/architecture
• Insufficient memory or disk space

Collect:

• Startup command
• Config file path, with secrets removed
• Logs
• Port usage
• Data directory path
• mach5-one version

Version endpoint does not respond

Check:

curl http://localhost:8080/version.txt

If this fails:

1. Confirm the Mach5 One process is running.
2. Confirm the configured server.http_port.
3. Check logs.
4. Check whether another process is using the port.

API reference does not load

Open:

http://localhost:8080/apis/rapidoc

If it fails:

1. Confirm /version.txt responds.
2. Confirm /apis/openapi.json responds.
3. Check logs for API startup errors.

Data Explorer does not load

Data Explorer is served from / when ui.dex_dist_path points to built UI assets.

Check your config:

[ui]
dex_dist_path = "/path/to/data-explorer/dist"

PostgreSQL client cannot connect

Default endpoint:

localhost:5432

Example:

psql -h localhost -p 5432 -U local -d default

Check:

• Mach5 One is running
• server.pg_port matches the client port
• No other PostgreSQL server is using that port
• Client logs and server logs

MCP client cannot connect

Default endpoint:

http://localhost:8080/mcp

Check:

• Mach5 One is running
• MCP client uses the configured HTTP port
• MCP client config is valid JSON/TOML/YAML as required
• Runtime version endpoint responds

Collect:

• MCP client name and version
• Config with secrets removed
• Runtime logs
• Client logs

Filing an issue

Use the most specific GitHub issue template.

Include:

Mach5 One version:
Release asset:
OS:
Architecture:
Install method:
Config path:
Command:
Expected behavior:
Actual behavior:
Logs:
Reproduction steps:

Never include secrets, private keys, credentials, customer data, or sensitive local file contents in public issues.