Skip to content

Error Codes Reference

Complete reference of Mailborder error codes and troubleshooting steps.

Overview

Mailborder uses structured error codes for:

  • SMTP errors - Email processing issues
  • Authentication errors - Login and session problems
  • API errors - Web interface and RPC communication
  • System errors - Service and configuration issues
  • Database errors - Data persistence failures

Error code format: MB-XXXX or SMTP-XXX

SMTP Error Codes

4xx Temporary Failures

Temporary errors that may succeed if retried.

SMTP-421 - Service Unavailable

Description: Mail server temporarily unavailable.

Common causes: - Server overloaded - Too many connections - Service restarting

User message: 

421 4.3.2 Service not available, closing transmission channel

Troubleshooting: 

# Check service status
sudo systemctl status postfix
sudo systemctl status mb-filter

# Check resource usage
top
df -h

# Check connection count
sudo netstat -an | grep :25 | wc -l

# Restart if needed
sudo systemctl restart mb-filter
sudo systemctl restart postfix

SMTP-450 - Mailbox Unavailable

Description: Requested mail action not taken (mailbox unavailable, busy, or temporarily blocked).

Common causes: - Greylisting in effect - Temporary mailbox lock - Quota temporarily exceeded

User message: 

450 4.7.1 <user@example.com>: Recipient address temporarily unavailable

Troubleshooting: 

# Check if greylisting is enabled
sudo mb-config get greylist.enabled

# Check mailbox status
sudo mb-test-recipient user@example.com

# Check logs
sudo grep "450" /var/log/mail.log

SMTP-451 - Local Error

Description: Requested action aborted due to local error.

Common causes: - Disk full - Out of memory - Database connection failure - Temporary file system issue

User message: 

451 4.3.0 Local error in processing

Troubleshooting: 

# Check disk space
df -h

# Check memory
free -m

# Check database
sudo mysql -u mailborder -p mailborder -e "SELECT 1"

# Check logs
sudo tail -n 100 /var/log/mailborder/mb-filter.log

SMTP-452 - Insufficient Storage

Description: Requested mail action not taken due to insufficient system storage.

Common causes: - Disk full - Quota exceeded - Quarantine directory full

User message: 

452 4.3.1 Insufficient system storage

Troubleshooting: 

# Check disk usage
df -h /var/spool/mailborder

# Check quarantine size
sudo mb-quarantine-stats --storage

# Clean up
sudo mb-quarantine-cleanup
sudo mb-maintenance --cleanup-logs

5xx Permanent Failures

Permanent errors that will not succeed if retried.

SMTP-550 - Mailbox Unavailable

Description: Requested action not taken (mailbox unavailable or does not exist).

Common causes: - Invalid recipient - Mailbox does not exist - Domain not accepted

User message: 

550 5.1.1 <user@example.com>: Recipient address rejected: User unknown

Troubleshooting: 

# Verify recipient
sudo mb-test-recipient user@example.com

# Check accepted domains
sudo mb-domain list

# Check recipient validation
sudo mb-config get policy.verify_recipient

SMTP-551 - User Not Local

Description: User not local; please try a different path.

Common causes: - Recipient domain not local - Relay not authorized - Open relay attempt

User message: 

551 5.7.1 <user@external.com>: Relay access denied

Troubleshooting: 

# Check relay configuration
sudo mb-config get relay.networks

# Verify domain type
sudo mb-domain list | grep external.com

# Test relay
sudo mb-test-relay

SMTP-552 - Storage Exceeded

Description: Requested mail action aborted due to exceeded storage allocation.

Common causes: - Message too large - Mailbox quota exceeded - Attachment size limit

User message: 

552 5.3.4 Message size exceeds fixed maximum message size

Troubleshooting: 

# Check size limit
sudo mb-config get email.max_message_size

# Increase if needed
sudo mb-config set email.max_message_size 104857600  # 100 MB
sudo mb-config reload

SMTP-553 - Mailbox Name Invalid

Description: Requested action not taken; mailbox name not allowed.

Common causes: - Invalid email address format - Prohibited characters - Policy rejection

User message: 

553 5.1.3 <invalid@address>: Mailbox name not allowed

Troubleshooting: 

# Check address format
# Valid: user@domain.com
# Invalid: @domain.com, user@, user

# Check policy rules
sudo mb-policy list

SMTP-554 - Transaction Failed

Description: Transaction failed for reasons not covered by other codes.

Common causes: - Spam detected - Virus found - Policy violation - Authentication failure

User message: 

554 5.7.1 Message rejected due to policy violations

Troubleshooting: 

# Check rejection reason in logs
sudo grep "554" /var/log/mail.log | tail -n 20

# Check spam score
sudo tail -f /var/log/mailborder/spam.log

# Check virus scan
sudo tail -f /var/log/mailborder/virus.log

# Check policies
sudo tail -f /var/log/mailborder/policy.log

Mailborder-Specific Errors

MB-1000 Series: Authentication Errors

MB-1001 - Invalid Credentials

Description: Username or password incorrect.

User message: "Invalid email or password"

Troubleshooting: 

# Check user exists
sudo mb-admin-list | grep user@example.com

# Reset password
sudo mb-admin-reset --email user@example.com

# Check if account locked
sudo mb-admin-list --locked

# Unlock if needed
sudo mb-admin-unlock --email user@example.com

MB-1002 - Account Locked

Description: Account locked due to too many failed login attempts.

User message: "Account locked due to multiple failed login attempts"

Troubleshooting: 

# Check lock status
sudo mb-admin-list --locked

# Unlock account
sudo mb-admin-unlock --email user@example.com

# Check failed attempts
SELECT email, failed_login_attempts, locked
FROM mb_users
WHERE email = 'user@example.com';

MB-1003 - Account Disabled

Description: User account has been disabled.

User message: "Account has been disabled"

Troubleshooting: 

# Check account status
sudo mb-admin-list | grep user@example.com

# Enable account
sudo mb-admin-enable --email user@example.com

MB-1004 - 2FA Required

Description: Two-factor authentication code required.

User message: "Two-factor authentication required"

Troubleshooting: 

# Check if 2FA enabled for user
sudo mb-2fa-list --email user@example.com

# Disable 2FA if needed (emergency)
sudo mb-2fa-disable --email user@example.com

# Regenerate backup codes
sudo mb-2fa-backup-codes --email user@example.com

MB-1005 - Invalid 2FA Code

Description: Two-factor authentication code is incorrect or expired.

User message: "Invalid or expired authentication code"

Troubleshooting: 

# Verify TOTP is working
sudo mb-2fa-verify --email user@example.com --code 123456

# Check time sync (important for TOTP)
sudo timedatectl

# Use backup code instead
# (User should have backup codes from enrollment)

# Reset 2FA if necessary
sudo mb-2fa-disable --email user@example.com
sudo mb-2fa-enable --email user@example.com

MB-1006 - Session Expired

Description: User session has expired.

User message: "Your session has expired. Please log in again."

Troubleshooting: 

# Check session timeout setting
sudo mb-config get authentication.session_timeout

# Adjust timeout if needed
sudo mb-config set authentication.session_timeout 3600  # 1 hour

# Check Redis (session storage)
redis-cli ping

# Clear old sessions
redis-cli FLUSHDB

MB-1007 - Invalid Session

Description: Session ID not found or invalid.

User message: "Invalid session. Please log in again."

Troubleshooting: 

# Check Redis connection
redis-cli ping

# Check session in database
SELECT * FROM mb_auth_sessions WHERE session_id = 'xxx';

# Clear browser cookies
# (User action)

MB-2000 Series: Database Errors

MB-2001 - Database Connection Failed

Description: Cannot connect to MariaDB database.

User message: "Database connection error. Please try again later."

Troubleshooting: 

# Check MariaDB status
sudo systemctl status mariadb

# Test connection
sudo mysql -u mailborder -p mailborder -e "SELECT 1"

# Check credentials
sudo cat /etc/mailborder/database.conf

# Check network
sudo netstat -tulpn | grep 3306

# Restart MariaDB
sudo systemctl restart mariadb

MB-2002 - Query Failed

Description: Database query execution failed.

User message: "Database error. Please contact support."

Troubleshooting: 

# Check MariaDB logs
sudo tail -n 100 /var/log/mysql/error.log

# Check table integrity
sudo mysql mailborder -e "CHECK TABLE mb_users"

# Repair table if needed
sudo mysql mailborder -e "REPAIR TABLE mb_users"

# Optimize database
sudo mb-maintenance --optimize-db

MB-2003 - Duplicate Entry

Description: Attempting to insert duplicate unique value.

User message: "Entry already exists"

Common causes: - Duplicate email address - Duplicate setting key - Duplicate policy name

Troubleshooting: 

# Check existing entries
sudo mb-admin-list | grep user@example.com

# Delete duplicate if needed
sudo mb-admin-delete --email old@example.com

MB-3000 Series: Email Processing Errors

MB-3001 - Spam Detected

Description: Message flagged as spam.

SMTP code: 554 User message: "Message rejected: Spam detected (score: 12.5)"

Troubleshooting: 

# Check spam score
sudo grep "MB-3001" /var/log/mailborder/spam.log

# Test email
sudo mb-spam-test /path/to/email.eml

# Adjust threshold if too sensitive
sudo mb-config set spam.threshold.reject 25.0

# Whitelist sender if false positive
sudo mb-whitelist add sender@example.com

MB-3002 - Virus Detected

Description: Virus or malware found in message.

SMTP code: 554 User message: "Message rejected: Virus detected (Win.Trojan.Generic)"

Troubleshooting: 

# Check virus name
sudo grep "MB-3002" /var/log/mailborder/virus.log

# Update virus signatures
sudo freshclam

# Whitelist if false positive (CAREFUL!)
sudo mb-antivirus-whitelist add-hash <file-hash>

# Check signature version
sudo sigtool --info /var/lib/clamav/daily.cvd

MB-3003 - Policy Violation

Description: Message violates configured policy.

SMTP code: 554 User message: "Message rejected: Policy violation"

Troubleshooting: 

# Check which policy matched
sudo grep "MB-3003" /var/log/mailborder/policy.log

# List policies
sudo mb-policy list

# Disable policy if needed
sudo mb-policy disable policy-name

# Add exception
sudo mb-policy add-exception sender@example.com

MB-3004 - GeoIP Block

Description: Message from blocked geographic location.

SMTP code: 554 User message: "Message rejected: Geographic restriction"

Troubleshooting: 

# Check sender country
sudo grep "MB-3004" /var/log/mailborder/geoip.log

# Test IP
sudo mb-geoip-test 203.0.113.50

# Whitelist sender
sudo mb-geoip-exempt add sender@example.com

# Or allow country temporarily
sudo mb-geoip-allow add CN

MB-3005 - Authentication Failed (SPF/DKIM/DMARC)

Description: Email failed authentication checks.

SMTP code: 554 User message: "Message rejected: Failed authentication (DMARC policy)"

Troubleshooting: 

# Check authentication results
sudo grep "MB-3005" /var/log/mailborder/auth.log

# Test specific email
sudo mb-auth-analyze <message-id>

# Adjust policy if too strict
sudo mb-config set dmarc.fail_action quarantine  # instead of reject

# Whitelist sender domain if legitimate
sudo mb-policy add auth-exception --from @domain.com

MB-4000 Series: Configuration Errors

MB-4001 - Invalid Configuration

Description: Configuration value is invalid.

User message: "Invalid configuration value"

Troubleshooting: 

# Validate configuration
sudo mb-config --verify

# Check specific setting
sudo mb-config get setting.name

# Reset to default
sudo mb-config reset setting.name

# View errors
sudo tail -n 50 /var/log/mailborder/mailborder.log

MB-4002 - Missing Configuration

Description: Required configuration value not set.

User message: "Configuration incomplete"

Troubleshooting: 

# Run setup again
sudo mb-setup

# Manually set missing value
sudo mb-config set relay.host mail.example.com

# Check configuration file
sudo cat /etc/mailborder/mailborder.conf

MB-4003 - Service Not Available

Description: Required service is not running.

User message: "Service unavailable. Please try again later."

Troubleshooting: 

# Check all services
sudo mb-status

# Start missing service
sudo systemctl start mb-rpcd
sudo systemctl start mb-filter

# Check dependencies
sudo systemctl status mariadb
sudo systemctl status redis-server

MB-5000 Series: API/RPC Errors

MB-5001 - API Authentication Failed

Description: Invalid API key or credentials.

User message: "API authentication failed"

Troubleshooting: 

# Generate new API key
sudo mb-api-key-generate --email user@example.com

# List API keys
sudo mb-api-key-list --email user@example.com

# Revoke old key
sudo mb-api-key-revoke --key mbv6_old_key

MB-5002 - API Rate Limit Exceeded

Description: Too many API requests in short period.

User message: "Rate limit exceeded. Please try again later."

Troubleshooting: 

# Check rate limit configuration
sudo mb-config get api.rate_limit

# Increase limit if needed
sudo mb-config set api.rate_limit 1000

# Check which endpoint
sudo grep "MB-5002" /var/log/mailborder/api.log

MB-5003 - RPC Communication Failed

Description: Cannot communicate with mb-rpcd.

User message: "Service communication error"

Troubleshooting: 

# Check mb-rpcd status
sudo systemctl status mb-rpcd

# Check socket
ls -lh /var/run/mailborder/mb-rpcd.sock

# Restart mb-rpcd
sudo systemctl restart mb-rpcd

# Check logs
sudo tail -n 100 /var/log/mailborder/mb-rpcd.log

Error Log Locations

Main Logs

Log File Content Rotation
/var/log/mailborder/mailborder.log General system log Daily
/var/log/mailborder/auth.log Authentication events Daily
/var/log/mailborder/spam.log Spam detection Daily
/var/log/mailborder/virus.log Virus scanning Daily
/var/log/mailborder/policy.log Policy enforcement Daily
/var/log/mailborder/geoip.log GeoIP filtering Daily
/var/log/mail.log Postfix SMTP log Daily

Error Analysis

Search for specific error: 

sudo grep "MB-1001" /var/log/mailborder/*.log
sudo grep "SMTP-550" /var/log/mail.log

Recent errors only: 

sudo tail -n 100 /var/log/mailborder/mailborder.log | grep ERROR

Error frequency: 

sudo grep ERROR /var/log/mailborder/mailborder.log | cut -d' ' -f5 | sort | uniq -c | sort -rn

Errors in last hour: 

sudo journalctl --since "1 hour ago" | grep ERROR

Common Error Patterns

Login Failures

Symptoms: Users unable to log in

Check: 

# Recent login failures
sudo grep "MB-1001" /var/log/mailborder/auth.log | tail -n 20

# Locked accounts
sudo mb-admin-list --locked

# Database connection
sudo mysql -u mailborder -p mailborder -e "SELECT 1"

Email Not Processing

Symptoms: Email stuck in queue or not delivered

Check: 

# Mail queue
sudo mailq

# Service status
sudo mb-status

# Recent errors
sudo tail -n 100 /var/log/mail.log | grep -i error

# Disk space
df -h

Web Interface Down

Symptoms: Cannot access web interface

Check: 

# Nginx status
sudo systemctl status nginx

# PHP-FPM status
sudo systemctl status php8.2-fpm

# mb-rpcd status
sudo systemctl status mb-rpcd

# Nginx error log
sudo tail -n 50 /var/log/nginx/mailborder-error.log

Database Errors

Symptoms: Database connection failures

Check: 

# MariaDB status
sudo systemctl status mariadb

# Connection test
sudo mysql -u mailborder -p mailborder -e "SELECT 1"

# MariaDB error log
sudo tail -n 100 /var/log/mysql/error.log

# Disk space
df -h /var/lib/mysql

Getting Help

Diagnostic Report

Generate diagnostic report: 

sudo mb-doctor > /tmp/mailborder-diagnostic-$(date +%Y%m%d).txt

Includes: - Service status - Error log excerpts - Configuration validation - Resource usage - Recent error patterns

Support Information

When contacting support, include:

  1. Error code - MB-XXXX or SMTP-XXX
  2. Log excerpts - Relevant error messages
  3. Diagnostic report - Output of mb-doctor
  4. Steps to reproduce - How to trigger the error
  5. System info - OS version, Mailborder version

Get Mailborder version: 

sudo mb-status --version

Get OS info: 

lsb_release -a
uname -a

See Also