Troubleshooting

// In your collection
export const Media: CollectionConfig = {
  slug: 'media', // Must match plugin config
};

// In your plugin config
cloudinaryStorage({
  collections: {
    'media': true, // Must match collection slug
  },
})

export default buildConfig({
  plugins: [
    cloudinaryStorage({ /* ... */ }), // Register plugin first
    // ... other plugins
  ],
  collections: [
    Media,
    // ... other collections
  ],
})

# Stop the server (Ctrl+C) and restart
npm run dev
# or
yarn dev

export default buildConfig({
  // ... your config
  onInit: async (payload) => {
    // Log the complete Media collection configuration
    console.log('Media collection fields:',
      payload.collections['media'].config.fields.map(f => f.name)
    );
  }
});

customFields: [
  {
    name: 'alt',
    type: 'text', // Correct type
    label: 'Alt Text',
  },
  // Not:
  // { name: 'alt', label: 'Alt Text' } // Missing type!
]

// Migrate existing documents
const media = await payload.find({
  collection: 'media',
  limit: 1000,
});

for (const doc of media.docs) {
  await payload.update({
    collection: 'media',
    id: doc.id,
    data: {
      alt: doc.alt || '',
    },
  });
}

# .env.local or .env
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

import { v2 as cloudinary } from 'cloudinary';

cloudinary.config({
  cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
});

// Test upload
cloudinary.uploader.upload(
  'test-image.jpg',
  { folder: 'test' },
  (error, result) => {
    if (error) console.error('Error:', error);
    else console.log('Success:', result);
  }
);

cloudinaryStorage({
  folder: 'my-app-media', // Base folder path
  // ...
})

cloudinaryStorage({
  folder: 'media',
  supportDynamicFolderMode: true, // Default: true
  // ...
})

cloudinaryStorage({
  publicID: {
    enabled: true,
    useFilename: true,
    uniqueFilename: true, // Adds unique suffix
  },
})

publicID: {
  enabled: true,
  generatePublicID: (filename, prefix, folder) => {
    const timestamp = Date.now();
    const random = Math.random().toString(36).substring(7);
    const safeName = filename.replace(/[^a-z0-9]/gi, '-').toLowerCase();
    return `${folder}/${safeName}-${timestamp}-${random}`;
  },
}

cloudinaryStorage({
  folder: 'payload-media',
  supportDynamicFolderMode: true, // Default: true
  // ...
})

cloudinaryStorage({
  versioning: {
    enabled: true,
    storeHistory: true, // Required to store history
  },
})

const media = await payload.findByID({
  collection: 'media',
  id: 'doc-id',
});

console.log(media.versions); // Should be an array

cloudinaryStorage({
  versioning: {
    enabled: true,
    autoInvalidate: true, // Invalidate old versions in CDN
  },
})

# .env.local (Next.js)
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=your-cloud-name

console.log('Public ID:', media.cloudinary.public_id);
// Should be something like: "payload-media/image-name-123456"
// Not: "//payload-media//image-name" or similar

https://res.cloudinary.com/{cloud_name}/image/upload/{public_id}.{format}

// Correct:
`w_400,h_300,c_fill,q_auto`

// Incorrect:
`width:400,height:300` // Wrong syntax
`w_400 h_300` // Missing commas

// Test 1: Basic resize
`w_400`

// Test 2: Add crop
`w_400,c_fill`

// Test 3: Add quality
`w_400,c_fill,q_auto`

if (media.cloudinary.format === 'pdf') {
  // PDF-specific code
}

// Correct:
`pg_1,w_300,h_400,c_fill,q_auto,f_jpg/${public_id}.pdf`

// Incorrect:
`page_1/${public_id}.pdf` // Wrong syntax
`pg_1/${public_id}.pdf` // Missing format conversion (f_jpg)

const page = media.cloudinary.selected_page || 1;
const totalPages = media.cloudinary.pages || 1;

if (page > totalPages) {
  // Page out of range
}

const start = Date.now();
await payload.create({
  collection: 'media',
  data: { /* ... */ },
});
console.log(`Upload took ${Date.now() - start}ms`);

// Don't load full-size images for thumbnails
// Bad:
`${public_id}.${format}`

// Good:
`w_200,h_200,c_fill,q_auto,f_auto/${public_id}.${format}`

`q_auto,f_auto/${public_id}.${format}`

<img src={url} loading="lazy" />

const doc = await payload.create({
  collection: 'media',
  data: { /* ... */ },
});

if (!doc.cloudinary) {
  console.error('Cloudinary upload failed');
  // Check server logs for error details
}

cloudinaryStorage({
  enabled: true, // Default: true
  collections: {
    'media': true, // Must be enabled
  },
})

import { v2 as cloudinary } from 'cloudinary';

// List all resources in folder
const result = await cloudinary.api.resources({
  type: 'upload',
  prefix: 'payload-media',
  max_results: 500,
});

// Check which ones exist in Payload
for (const resource of result.resources) {
  const exists = await payload.find({
    collection: 'media',
    where: {
      'cloudinary.public_id': {
        equals: resource.public_id,
      },
    },
  });
  
  if (exists.docs.length === 0) {
    // Orphaned - safe to delete
    await cloudinary.uploader.destroy(resource.public_id);
  }
}