How to fix messaging/invalid-payload: Malformed message payload in Firebase

// Validate your message payload structure
const message = {
  token: registrationToken,
  notification: {
    title: 'Notification Title',
    body: 'Notification body text'
  },
  data: {
    key1: 'value1',
    key2: 'value2'
  }
};

// Test JSON serialization
try {
  const jsonString = JSON.stringify(message);
  const parsed = JSON.parse(jsonString);
  console.log('JSON is valid');
} catch (error) {
  console.error('Invalid JSON:', error.message);
}

// Common JSON errors to check:
// - Trailing commas in objects/arrays
// - Missing quotes around keys
// - Unclosed brackets or braces
// - Invalid escape sequences in strings

// Reserved keywords that CANNOT be used in data payload
const reservedKeywords = [
  'from',
  'notification',
  'message_type',
  'collapse_key'
];

// Keys starting with these prefixes are also forbidden
const forbiddenPrefixes = ['google.', 'gcm.', 'gcm.notification.'];

// Example of checking data payload
const dataPayload = {
  userId: '12345',           // OK
  customKey: 'customValue',  // OK
  // 'from': 'sender',       // FORBIDDEN - reserved keyword
  // 'gcm.notification.title': 'Title'  // FORBIDDEN - gcm prefix
};

// Validation function
function validateDataKeys(data) {
  const keys = Object.keys(data || {});

  for (const key of keys) {
    // Check reserved keywords
    if (reservedKeywords.includes(key)) {
      console.error(`Reserved keyword "${key}" found in data payload`);
      return false;
    }

    // Check forbidden prefixes
    for (const prefix of forbiddenPrefixes) {
      if (key.startsWith(prefix)) {
        console.error(`Forbidden key prefix "${prefix}" in key "${key}"`);
        return false;
      }
    }
  }

  return true;
}

// Use the validator
if (!validateDataKeys(message.data)) {
  console.error('Data payload contains reserved keywords');
}

// INCORRECT - non-string values in data payload
const incorrectMessage = {
  token: registrationToken,
  data: {
    userId: 12345,              // Number - will cause error
    isActive: true,             // Boolean - will cause error
    metadata: { key: 'value' }, // Object - will cause error
    items: ['a', 'b', 'c']      // Array - will cause error
  }
};

// CORRECT - all values converted to strings
const correctMessage = {
  token: registrationToken,
  data: {
    userId: '12345',                          // String
    isActive: 'true',                         // String
    metadata: JSON.stringify({ key: 'value' }), // Serialized object
    items: JSON.stringify(['a', 'b', 'c'])    // Serialized array
  }
};

// Helper function to convert data payload
function stringifyDataPayload(data) {
  const stringified = {};

  for (const [key, value] of Object.entries(data)) {
    if (typeof value === 'string') {
      stringified[key] = value;
    } else if (value === null || value === undefined) {
      // Skip null/undefined values or convert to empty string
      stringified[key] = '';
    } else {
      // Convert objects, arrays, numbers, booleans to JSON strings
      stringified[key] = JSON.stringify(value);
    }
  }

  return stringified;
}

// Use the helper
message.data = stringifyDataPayload(message.data);

// Correct message with platform-specific configs
const message = {
  token: registrationToken,

  // Common notification (optional)
  notification: {
    title: 'Title',
    body: 'Body text'
  },

  // Android-specific configuration
  android: {
    priority: 'high',  // 'normal' or 'high'
    notification: {
      sound: 'default',
      color: '#ff0000',
      tag: 'notification-tag'
    },
    ttl: 3600  // Time to live in seconds (number, not string)
  },

  // iOS APNS configuration
  apns: {
    payload: {
      aps: {
        alert: {
          title: 'iOS Title',
          body: 'iOS Body'
        },
        sound: 'default',
        badge: 1  // Number, not string
      }
    },
    headers: {
      'apns-priority': '10'  // String value
    }
  },

  // Web Push configuration
  webpush: {
    notification: {
      title: 'Web Title',
      body: 'Web Body',
      icon: 'https://example.com/icon.png'
    },
    fcmOptions: {
      link: 'https://example.com'
    }
  }
};

// Common mistakes:
// - Using string values for numeric fields (ttl, badge)
// - Incorrect priority values (must be 'normal' or 'high' for Android)
// - Missing required nested structures (apns.payload.aps)
// - Invalid URL formats in webpush fields

// Step 1: Test minimal notification-only message
const minimalMessage = {
  token: registrationToken,
  notification: {
    title: 'Test',
    body: 'Test message'
  }
};

try {
  await admin.messaging().send(minimalMessage);
  console.log('Minimal message sent successfully');
} catch (error) {
  console.error('Minimal message failed:', error.message);
  // If this fails, issue is with token or basic setup
}

// Step 2: Add data payload
const withData = {
  ...minimalMessage,
  data: {
    test: 'value'
  }
};

try {
  await admin.messaging().send(withData);
  console.log('Message with data sent successfully');
} catch (error) {
  console.error('Data payload caused error:', error.message);
  // Issue is in data payload structure
}

// Step 3: Add platform-specific configs incrementally
const withAndroid = {
  ...withData,
  android: {
    priority: 'high'
  }
};

// Continue adding configurations one at a time to isolate
// which part of the payload is causing the malformation error

// Enable debug logging for Firebase Admin SDK
process.env.DEBUG = 'firebase-admin:*';

// Use dry run mode to validate without sending
const message = {
  // your message configuration
};

try {
  // Dry run validates the message without actually sending it
  const response = await admin.messaging().send(message, true);
  console.log('Message validation passed:', response);
} catch (error) {
  console.error('Validation failed:', error.message);

  // Check error details
  if (error.errorInfo) {
    console.error('Error code:', error.errorInfo.code);
    console.error('Error message:', error.errorInfo.message);
  }

  // Log the full error object for debugging
  console.error('Full error:', JSON.stringify(error, null, 2));
}

// Additional validation: check payload size
const payloadSize = JSON.stringify(message).length;
console.log(`Payload size: ${payloadSize} bytes`);

if (payloadSize > 4096) {
  console.warn('Payload exceeds 4KB limit');
}

// Validate specific fields
if (message.data) {
  console.log('Data payload keys:', Object.keys(message.data));
  console.log('Data payload values types:',
    Object.entries(message.data).map(([k, v]) => `${k}: ${typeof v}`)
  );
}