Troubleshooting

Quick checks

1. Node.js 20+ (node --version)
2. Config present (ls hatago.config.json) for STDIO mode
3. Run with --verbose and read first error

Top 10 Issues

1. Command not found

Symptoms

hatago: command not found / npx: not found

Causes:

• Global install missing, or PATH not set

Fix:

• Use npx @himorishige/hatago-mcp-hub ... or add global bin to PATH

2. Config not found

Symptoms

ENOENT: hatago-config.json

Fix:

npx @himorishige/hatago-mcp-hub init
hatago serve --stdio --config ./hatago.config.json

Prevention: keep an example (hatago-config.example.json) and document copying.

3. Invalid JSON

Fix: validate with cat hatago.config.json | jq . and fix syntax.

4. Env var not found

Symptoms

${VAR} not found

Fix: export vars or add defaults (${VAR:-default}).

5. Child server fails to start

Causes: wrong command, missing deps, permissions.

Fix: run the server directly (e.g. npx @modelcontextprotocol/server-filesystem .) and read its logs.

6. Remote connect errors

Symptoms

ECONNREFUSED / timeout

Fixes:

• Verify URL and DNS
• Check firewall/proxy
• Increase timeouts on the remote side if applicable

7. 401/403 Unauthorized

Fixes:

• Ensure Authorization header present
• Refresh token / check scopes

8. No tools listed

Fixes:

• Confirm child server is running
• Check notifications/tools/list_changed support and wait a moment
• Read internal resource hatago://servers to confirm connected servers

9. Logs too noisy or silent

Use --verbose for debug, or --quiet to reduce noise.

10. Port already in use (HTTP)

Change port: hatago serve --http --port 3536.

Diagnose by layers

Layer	Symptom	Command	First action
1. Startup	command not found	which hatago	Use npx or fix PATH
2. Config	Invalid config	`cat config	jq .`
3. Env	${VAR} not found	echo $VAR	Export or set default
4. Spawn	spawn ENOENT	which npx	Use absolute path
5. Network	ECONNREFUSED	curl -I <url>	Verify URL/firewall
6. Auth	401/403	echo $TOKEN	Refresh token/scopes
7. Timeout	Request timeout	time curl <url>	Increase timeout

Useful commands

hatago serve --verbose
hatago serve --tags development

Need help?

• GitHub Issues: https://github.com/himorishige/hatago-hub/issues
• Discussions: https://github.com/himorishige/hatago-hub/discussions