How to fix StorageApiError: Invalid key in Supabase

// ❌ Wrong - leading slash
const { data, error } = await supabase.storage
  .from('bucket')
  .upload('/path/to/file.png', file);

// ✅ Correct - no leading slash
const { data, error } = await supabase.storage
  .from('bucket')
  .upload('path/to/file.png', file);

if (error) {
  console.error('Upload error:', error.message);
}

// ❌ Wrong - empty path
const filePath = '';
const { data, error } = await supabase.storage
  .from('bucket')
  .upload(filePath, file);
// Error: Invalid key:

// ✅ Correct - provide a valid file path
const filePath = 'documents/my-file.pdf';
const { data, error } = await supabase.storage
  .from('bucket')
  .upload(filePath, file);

if (error) {
  console.error('Error:', error.message);
}

// ❌ Wrong - contains special characters
const fileName = 'file#1.png';           // Contains #
const fileName = '100%done.pdf';        // Contains %
const fileName = 'what?.docx';          // Contains ?

// ✅ Correct - safe characters only
const fileName = 'file-1.png';          // Replace # with -
const fileName = '100-done.pdf';        // Replace % with -
const fileName = 'what.docx';           // Remove ?

// Safe function to sanitize file names
function sanitizeFileName(fileName: string): string {
  return fileName
    .replace(/[#%?]/g, '-')              // Replace invalid chars with dash
    .replace(/\s+/g, '_')               // Replace spaces with underscore
    .replace(/[^a-zA-Z0-9._\-/]/g, ''); // Remove other unsafe chars
}

const safePath = sanitizeFileName(originalFileName);
const { data, error } = await supabase.storage
  .from('bucket')
  .upload(safePath, file);

import { v4 as uuid } from 'uuid';

// ❌ Problematic - non-ASCII characters
const fileName = '文件.pdf';  // Chinese characters
const filePath = `uploads/${fileName}`;
// Gets encoded to %E6%96%87%E4%BB%B6.pdf which may fail

// ✅ Best approach - use UUID
const fileExtension = originalFile.name.split('.').pop();
const safeFileName = `${uuid()}.${fileExtension}`;
const filePath = `uploads/${safeFileName}`;

const { data, error } = await supabase.storage
  .from('bucket')
  .upload(filePath, file);

if (error) {
  console.error('Upload error:', error.message);
}

// Alternative - sanitize and preserve original name in metadata
function sanitizeFileName(fileName: string): string {
  return fileName
    .replace(/[^a-zA-Z0-9._-]/g, '_')  // Replace non-ASCII with underscore
    .toLowerCase()
    .substring(0, 255);                  // Limit length
}

const originalName = originalFile.name;
const safeName = sanitizeFileName(originalName);
const filePath = `uploads/${safeName}`;

const { data, error } = await supabase.storage
  .from('bucket')
  .upload(filePath, file, {
    metadata: {
      originalFileName: originalName
    }
  });

// ❌ Wrong - double slash
const filePath = 'uploads//my-file.pdf';      // Double slash
const filePath = 'uploads/./file.pdf';        // Unnecessary dot
const filePath = 'uploads/../file.pdf';       // Relative path traversal

// ✅ Correct - clean paths
const filePath = 'uploads/my-file.pdf';
const filePath = 'uploads/subfolder/file.pdf';

// Safe path builder function
function buildFilePath(...segments: string[]): string {
  return segments
    .filter(s => s && s.length > 0)      // Remove empty segments
    .join('/')
    .replace(/\/+/g, '/')               // Remove double slashes
    .replace(/^\//, '');                // Remove leading slash
}

const filePath = buildFilePath('uploads', userId, fileName);
const { data, error } = await supabase.storage
  .from('bucket')
  .upload(filePath, file);

function validateFilePath(filePath: string): { valid: boolean; error?: string } {
  // Check not empty
  if (!filePath || filePath.trim().length === 0) {
    return { valid: false, error: 'File path cannot be empty' };
  }

  // Check not too long
  if (filePath.length > 1024) {
    return { valid: false, error: 'File path exceeds 1024 bytes' };
  }

  // Check no leading slash
  if (filePath.startsWith('/')) {
    return { valid: false, error: 'File path cannot start with /' };
  }

  // Check no double slashes
  if (filePath.includes('//')) {
    return { valid: false, error: 'File path cannot contain //' };
  }

  // Check for invalid characters
  const invalidChars = ['%', '#', '?'];
  for (const char of invalidChars) {
    if (filePath.includes(char)) {
      return { valid: false, error: `File path cannot contain '${char}' character` };
    }
  }

  return { valid: true };
}

// Usage
const validation = validateFilePath(filePath);
if (!validation.valid) {
  console.error('Invalid file path:', validation.error);
  return;
}

const { data, error } = await supabase.storage
  .from('bucket')
  .upload(filePath, file);

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

// Verify bucket exists and you have access
const { data: buckets, error: listError } = await supabase.storage.listBuckets();

if (listError) {
  console.error('Cannot list buckets:', listError.message);
} else {
  const bucketNames = buckets.map(b => b.name);
  console.log('Available buckets:', bucketNames);
  
  if (!bucketNames.includes('your-bucket')) {
    console.error('Bucket "your-bucket" not found');
  }
}

// Then attempt upload
const { data, error } = await supabase.storage
  .from('your-bucket')
  .upload('valid/path/file.png', file);

if (error) {
  console.error('Upload error:', error.message);
}