BugWP logo BugWP
Back to Community
Home / Community / General

Resolving Common MailPoet Database Migration and Connection Errors

29 threads Sep 9, 2025

Content

If you use MailPoet – Newsletters, Email Marketing, and Automation, you might have encountered a frustrating error related to database migrations or connections, especially after updating the plugin, changing your PHP version, or moving your site to a new server. These errors often prevent you from accessing key features of the plugin.

This guide compiles the most common database-related issues reported by users and provides step-by-step solutions to get your MailPoet installation back on track.

Why Do These Errors Happen?

MailPoet uses a system of database "migrations" to update its table structure whenever a new version is released. If this automated process is interrupted—by a server timeout, incorrect permissions, or a corrupted table—it can fail partway through. This leaves your database in an incomplete state, causing errors on subsequent visits. Server migrations can also change database connection strings or cause table corruption, leading to similar problems.

Common Error Messages and Their Solutions

1. "Migration Failed" or "Column not found" Errors

These are the most frequent issues. You'll see messages like Migration "MailPoetMigrationsDbMigration_20230111_120000" failed or SQLSTATE[42S22]: Column not found: 1054 Unknown column.

Solution: Run Migrations Manually via WP-CLI
A powerful fix discovered by the community is to use WordPress's command-line tool (WP-CLI) to force all migrations to run again. This often resolves multiple missing column errors at once.

  1. Access your website's server via SSH.
  2. Navigate to your WordPress root directory.
  3. Run the command: wp mailpoet:migrations:run
  4. This will execute all necessary database updates. After it completes, check your WordPress admin to see if the error is resolved.

Solution: Manual Database Check and Repair
If WP-CLI is not an option, you may need to inspect the database manually.

  1. Deactivate the MailPoet plugin from your WordPress Plugins page.
  2. Use a database management tool like phpMyAdmin (provided by your host) to access your WordPress database.
  3. Locate the wp_mailpoet_migrations table (your prefix may differ) and note the most recent "migration" entry that ran successfully. This can help identify where the process failed.
  4. Consult the official MailPoet knowledge base for specific SQL queries to manually add missing columns or fix table structures. Warning: Always create a full database backup before making any manual changes.
  5. Reactivate the plugin.

2. "Could not connect to the database" Error

This often occurs after migrating a site to a new host. The error indicates that MailPoet cannot establish a connection, even if WordPress itself is working.

Solution: Check DB_HOST Setting
The most common fix is to change the database host from 'localhost' to '127.0.0.1' in your wp-config.php file. However, some hosts (like IONOS) require a specific hostname. If changing this value crashes your site, revert it and contact your hosting provider to confirm the correct DB_HOST value for your server environment.

Solution: Check MySQL Socket Path
If changing the host doesn't work, the issue may be with the PHP MySQL socket configuration.

  1. Contact your host to get the correct path to the MySQL socket (often something like /var/run/mysqld/mysqld.sock).
  2. Edit your php.ini file (your host can help you locate it) and find the line for pdo_mysql.default_socket.
  3. Set the value to the socket path provided by your host: pdo_mysql.default_socket = /var/run/mysqld/mysqld.sock
  4. Save the file and restart your web server.

3. "Base table or view not found" Error

Errors like Table 'wp_mailpoet_subscriber_segment' doesn't exist suggest crucial plugin tables are missing, often due to a failed installation or migration.

Solution: Reinstall the Plugin
A complete reinstall can often rebuild the missing tables.

  1. In WordPress, deactivate and delete the MailPoet plugin. When prompted, choose NOT to delete the plugin data. This will preserve your subscribers and settings.
  2. Install and activate MailPoet again from the Plugins → Add New page.
  3. The plugin should run its setup and create any missing tables.

Preventing Future Issues

  • Backups First: Always create a full backup of your site's files and database before updating any major plugin, PHP version, or migrating your site.
  • Check Hosting Requirements: Ensure your server meets the minimum requirements for the latest version of MailPoet and WordPress.
  • Update in a Staging Environment: If possible, test plugin updates on a staging copy of your site first to identify potential conflicts.

Database errors can be complex, but these steps resolve the majority of issues reported by the MailPoet community. If problems persist, searching the MailPoet knowledge base for your specific error message can often yield more targeted solutions.

Related Support Threads Support