wiki/deploy-mcp/Troubleshooting.md

← Back to Home

Troubleshooting

Common issues and solutions when using deploy-mcp.

Config File Not Found

Symptom: Server fails to start with Failed to load config from ~/.deploy-mcp.json.

Cause: The config file does not exist or is not valid JSON.

Solution:

1. Create ~/.deploy-mcp.json (see Configuration for full format):

{
  "connections": {
    "myserver": {
      "host": "server.example.com",
      "username": "deploy",
      "keyPath": "~/.ssh/id_ed25519",
      "remotePath": "/var/www/html",
      "localPath": "C:/projects/mysite/src"
    }
  }
}

2. Or set the DEPLOY_MCP_CONFIG environment variable to an alternate path.

SSH Connection Failures

Symptom: deploy_status returns FAILED or upload/download operations time out.

Cause: SSH cannot authenticate or reach the server.

Solutions:

Check	Fix
Host reachable	Verify hostname/IP and port in config
Key auth	Ensure keyPath points to a valid private key and the public key is in remote authorized_keys
BatchMode	Connection uses BatchMode=yes; password-based auth will fail silently
Firewall	Confirm SSH port is open on the remote server
ConnectTimeout	The client sets a 10-second connect timeout; check network latency

Test manually:

ssh -o BatchMode=yes -i ~/.ssh/id_ed25519 user@host echo ok

Connection Not Found

Symptom: Connection "name" not found. Available: ...

Cause: The connection parameter does not match any key in connections.

Solution:

• Run deploy_list_connections to see available names.
• Omit the connection parameter to use the default.
• Add the missing connection to ~/.deploy-mcp.json.

Upload/Download Failures

Symptom: deploy_upload or deploy_download returns FAILED: Command failed: scp.

Common Causes:

Cause	Solution
Remote path does not exist	Create the directory first: deploy_remote_exec with mkdir -p /path
Permission denied	Ensure the SSH user has write access to the remote path
Disk full	Check remote disk: deploy_disk_usage
File too large	The operation timeout is 120 seconds; very large transfers may exceed this

Rsync Sync Failures

Symptom: deploy_sync returns errors about rsync.

Common Causes:

Cause	Solution
rsync not installed locally	Install rsync (e.g. apt install rsync or via Git Bash on Windows)
rsync not installed on remote	Install rsync on the server
Trailing slash issues	The tool auto-appends / to local paths for content sync
--delete removes files	This is expected; rsync mirrors the local directory. Use dry_run: true first

Always preview with dry run:

deploy_sync(local_path: "./src", remote_path: "/var/www/html", dry_run: true)

Rollback Issues

Symptom: deploy_rollback fails with "previous directory does not exist".

Cause: No previous release directory exists at the specified path.

Solution:

1. Use deploy_backup_before to create a backup before deploying:

deploy_backup_before(remote_path: "/var/www/html")

This creates a timestamped copy like /var/www/html.backup-2026-05-09T12-00-00.

2. For rollback, provide the correct paths:

deploy_rollback(
  current_dir: "/var/www/html",
  previous_dir: "/var/www/html.backup-2026-05-09T12-00-00"
)

The rollback performs an atomic swap: current becomes previous and vice versa.

Permission Issues

Symptom: Deployed files have wrong permissions; site returns 403 errors.

Solution:

Use deploy_permissions to fix file and directory permissions:

deploy_permissions(remote_path: "/var/www/html")

This sets:

• Files: 644 (owner read/write, group/other read)
• Directories: 755 (owner full, group/other read/execute)

For web server ownership issues, use deploy_remote_exec:

deploy_remote_exec(command: "chown -R www-data:www-data /var/www/html")

Joomla Sync Script Not Found

Symptom: deploy_sync_joomla returns "sync-joomla.php not found".

Cause: The sync-joomla.php script cannot be located.

Solution:

Set platformPath in ~/.deploy-mcp.json:

{
  "platformPath": "A:/moko-platform"
}

The tool checks these paths in order:

1. {platformPath}/deploy/sync-joomla.php
2. A:/moko-platform/deploy/sync-joomla.php

Operation Timeout

Symptom: Commands fail after 120 seconds (2 minutes).

Cause: The default command timeout is 120,000 ms. Large file transfers or slow networks may exceed this.

Solution:

• For large deployments, use deploy_sync (rsync) which is more efficient than deploy_upload (scp).
• Break large uploads into smaller batches.
• The Joomla sync tool has a longer timeout of 5 minutes (300,000 ms).

---

Built on MokoStandards

---

Repo: deploy-mcp · MokoStandards

Revision	Date	Author	Description
1.0	2026-05-09	Moko Consulting	Initial version