Troubleshooting

Troubleshooting

Connection Issues

"Connection refused" or "Connection timed out"

Diagnosis:

wp_test_connection("site-name")

Fixes:

1. Verify hostname and port are correct
2. Test manually: ssh -p PORT user@host
3. Check if SSH is running: contact hosting provider
4. Check firewall allows your IP address
5. Some hosts block SSH after failed attempts - wait 15 minutes or contact support

"Permission denied (publickey)"

SSH key is not accepted by the server.

1. Check key permissions: chmod 600 ~/.ssh/id_rsa
2. Verify the key is added to the server's ~/.ssh/authorized_keys
3. Check key_path in your site config: wp_get_site("site-name")
4. Try: ssh -i ~/.ssh/your_key -v user@host for detailed error output

"sshpass: command not found"

Only needed for password authentication.

# macOS
brew install sshpass

# Ubuntu/Debian
sudo apt install sshpass

Better solution: Switch to SSH key auth to avoid this dependency entirely.

"Host key verification failed"

The server's SSH fingerprint changed or hasn't been accepted yet.

# Accept the host key manually first
ssh user@host
# Type "yes" when prompted

WP-CLI Issues

"WP-CLI not found" or "wp: command not found"

WP-CLI is not installed on the server.

# Install on the server
ssh user@host
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp
wp --info

"Error: This does not appear to be a WordPress installation"

The wp_path in your site config points to the wrong directory.

# Check current config
wp_get_site("site-name")

# Update the path
wp_update_site("site-name", wp_path="/correct/path/to/wordpress")

Find the correct path: ssh user@host "find / -name wp-config.php 2>/dev/null"

WP-CLI commands timeout

Large sites may need more time for operations like database exports or full scans.

• Run scans during low-traffic hours
• Use individual scan tools instead of wp_full_scan for targeted checks
• Check server resources (CPU, memory, disk I/O)

Scan Issues

Scan finds nothing but site is clearly hacked

Some malware hides in the database, not files:

# Check database specifically
wp_check_db_injections("site-name")

# Check for DB campaign markers
wp_delete_malware_options("site-name", dry_run=True)

# Check for self-hiding plugins (invisible to wp plugin list)
wp_scan_hidden_plugins("site-name")

Too many false positives

Known false positives:

• BuddyBoss: .htaccess files in bb_videos, bb_medias, bb_documents upload dirs
• BBPress/WbcomTeam: Plugin names match suspicious name patterns
• Image plugins: Base64 encoding for image data handling
• Build artifacts: Minified JS files

Use wp_read_file() to inspect flagged files before acting.

Scan is very slow

• Network latency: Check ping server-host
• Server load: Run during off-peak hours
• Large site: Use targeted scans (wp_verify_core, wp_scan_hidden_admins) instead of wp_full_scan

Cleanup Issues

"Self-healing" malware keeps coming back

The malware recreates itself after deletion. Look for self-healing plugins:

# Detect hidden plugins FIRST
wp_scan_hidden_plugins("site-name")

Critical: Delete the self-healing plugin directory BEFORE deleting users or DB markers. The plugin recreates them on every page load.

Passwords reset but users can still log in

Old sessions may still be valid. Regenerate salts to invalidate all sessions:

wp_regenerate_salts("site-name")

Cleanup completed but site is broken

1. Check if a legitimate plugin was accidentally removed
2. Restore from the database backup created in Step 1 of cleanup
3. Check the quarantine directory for files that may need restoration
4. Review the cleanup log: ~/.wp-malware-cleanup/logs/site-name.log

Threat Database Issues

wp_threat_db_stats returns an error

The database module isn't loading properly.

1. Check that database_v2.py exists in the MCP server directory
2. Restart the MCP server (restart Claude Code)
3. Check for Python import errors in the MCP server output

cleanup_records stays at 0

The auto-learning pipeline isn't recording. Check:

1. THREAT_DB_AVAILABLE is True (database module loaded successfully)
2. The threat database file exists at ~/.wp-malware-cleanup/threat_intel.db
3. Run a scan on a site with known issues - records should appear
4. Check file permissions on the database file

Sync fails

wp_threat_db_sync() requires internet access to reach GitHub.

1. Check internet connectivity
2. Check if GitHub is accessible from your network
3. Try again later (GitHub may have rate limiting)

MCP Server Issues

Tools not appearing in Claude Code

1. Verify registration: claude mcp list
2. Restart Claude Code completely (close and reopen)
3. Check the MCP config in ~/.claude.json
4. Verify the Python venv path is correct

MCP server crashes

Check the server logs:

# Run server directly to see errors
~/.claude/wp-malware-cleanup-mcp/.venv/bin/python ~/.claude/wp-malware-cleanup-mcp/server.py

Common causes:

• Missing Python dependencies: uv pip install -r requirements.txt
• Python version mismatch: Needs Python 3.12+
• Corrupted sites.json: Delete and re-add sites