s3db.js 11.2.3 → 11.2.4

package/dist/s3db.cjs.js

@@ -222,7 +222,7 @@ function calculateEffectiveLimit(config = {}) {
 }
 
 class BaseError extends Error {
-  constructor({ verbose, bucket, key, message, code, statusCode, requestId, awsMessage, original, commandName, commandInput, metadata, suggestion, description, ...rest }) {
+  constructor({ verbose, bucket, key, message, code, statusCode, requestId, awsMessage, original, commandName, commandInput, metadata, description, ...rest }) {
     if (verbose) message = message + `
 
 Verbose:
@@ -247,7 +247,6 @@ ${JSON.stringify(rest, null, 2)}`;
     this.commandName = commandName;
     this.commandInput = commandInput;
     this.metadata = metadata;
-    this.suggestion = suggestion;
     this.description = description;
     this.data = { bucket, key, ...rest, verbose, message };
   }
@@ -265,7 +264,6 @@ ${JSON.stringify(rest, null, 2)}`;
       commandName: this.commandName,
       commandInput: this.commandInput,
       metadata: this.metadata,
-      suggestion: this.suggestion,
       description: this.description,
       data: this.data,
       original: this.original,
@@ -406,26 +404,26 @@ function mapAwsError(err, context = {}) {
   const metadata = err.$metadata ? { ...err.$metadata } : void 0;
   const commandName = context.commandName;
   const commandInput = context.commandInput;
-  let suggestion;
+  let description;
   if (code === "NoSuchKey" || code === "NotFound") {
-    suggestion = "Check if the key exists in the specified bucket and if your credentials have permission.";
-    return new NoSuchKey({ ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = "The specified key does not exist in the bucket. Check if the key exists and if your credentials have permission to access it.";
+    return new NoSuchKey({ ...context, original: err, metadata, commandName, commandInput, description });
   }
   if (code === "NoSuchBucket") {
-    suggestion = "Check if the bucket exists and if your credentials have permission.";
-    return new NoSuchBucket({ ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = "The specified bucket does not exist. Check if the bucket name is correct and if your credentials have permission to access it.";
+    return new NoSuchBucket({ ...context, original: err, metadata, commandName, commandInput, description });
   }
   if (code === "AccessDenied" || err.statusCode === 403 || code === "Forbidden") {
-    suggestion = "Check your credentials and bucket policy.";
-    return new PermissionError("Access denied", { ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = "Access denied. Check your AWS credentials, IAM permissions, and bucket policy.";
+    return new PermissionError("Access denied", { ...context, original: err, metadata, commandName, commandInput, description });
   }
   if (code === "ValidationError" || err.statusCode === 400) {
-    suggestion = "Check the request parameters and payload.";
-    return new ValidationError("Validation error", { ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = "Validation error. Check the request parameters and payload format.";
+    return new ValidationError("Validation error", { ...context, original: err, metadata, commandName, commandInput, description });
   }
   if (code === "MissingMetadata") {
-    suggestion = "Check if the object metadata is present and valid.";
-    return new MissingMetadata({ ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = "Object metadata is missing or invalid. Check if the object was uploaded correctly.";
+    return new MissingMetadata({ ...context, original: err, metadata, commandName, commandInput, description });
   }
   const errorDetails = [
     `Unknown error: ${err.message || err.toString()}`,
@@ -433,27 +431,31 @@ function mapAwsError(err, context = {}) {
     err.statusCode && `Status: ${err.statusCode}`,
     err.stack && `Stack: ${err.stack.split("\n")[0]}`
   ].filter(Boolean).join(" | ");
-  suggestion = `Check the error details and AWS documentation. Original error: ${err.message || err.toString()}`;
-  return new UnknownError(errorDetails, { ...context, original: err, metadata, commandName, commandInput, suggestion });
+  description = `Check the error details and AWS documentation. Original error: ${err.message || err.toString()}`;
+  return new UnknownError(errorDetails, { ...context, original: err, metadata, commandName, commandInput, description });
 }
 class ConnectionStringError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: "Check the connection string format and credentials." });
+    const description = details.description || "Invalid connection string format. Check the connection string syntax and credentials.";
+    super(message, { ...details, description });
   }
 }
 class CryptoError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: "Check if the crypto library is available and input is valid." });
+    const description = details.description || "Cryptography operation failed. Check if the crypto library is available and input is valid.";
+    super(message, { ...details, description });
   }
 }
 class SchemaError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: "Check schema definition and input data." });
+    const description = details.description || "Schema validation failed. Check schema definition and input data format.";
+    super(message, { ...details, description });
   }
 }
 class ResourceError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: details.suggestion || "Check resource configuration, attributes, and operation context." });
+    const description = details.description || "Resource operation failed. Check resource configuration, attributes, and operation context.";
+    super(message, { ...details, description });
     Object.assign(this, details);
   }
 }
@@ -482,13 +484,12 @@ ${details.strictValidation === false ? "  \u2022 Update partition definition to
   \u2022 Update partition definition to use existing fields, OR
   \u2022 Use strictValidation: false to skip this check during testing`}
 
-Docs: https://docs.s3db.js.org/resources/partitions#validation
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#partitions
 `.trim();
     }
     super(message, {
       ...details,
-      description,
-      suggestion: details.suggestion || "Check partition definition, fields, and input values."
+      description
     });
   }
 }
@@ -547,7 +548,7 @@ Example fix:
   await db.connect();  // Plugin initialized here
   await db.createResource({ name: '${resourceName}', ... });  // Analytics resource created here
 
-Docs: https://docs.s3db.js.org/plugins/eventual-consistency#troubleshooting
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/eventual-consistency.md
 `.trim();
     super(message, {
       ...rest,
@@ -557,8 +558,260 @@ Docs: https://docs.s3db.js.org/plugins/eventual-consistency#troubleshooting
       configuredResources,
       registeredResources,
       pluginInitialized,
-      description,
-      suggestion: "Ensure resources are created after plugin initialization. Check plugin configuration and resource creation order."
+      description
+    });
+  }
+}
+class PluginError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      pluginName = "Unknown",
+      operation = "unknown",
+      ...rest
+    } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Plugin Error
+
+Plugin: ${pluginName}
+Operation: ${operation}
+
+Possible causes:
+1. Plugin not properly initialized
+2. Plugin configuration is invalid
+3. Plugin dependencies not met
+4. Plugin method called before installation
+
+Solution:
+Ensure plugin is added to database and connect() is called before usage.
+
+Example:
+  const db = new Database({
+    bucket: 'my-bucket',
+    plugins: [new ${pluginName}({ /* config */ })]
+  });
+
+  await db.connect();  // Plugin installed here
+  // Now plugin methods are available
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/README.md
+`.trim();
+    }
+    super(message, {
+      ...rest,
+      pluginName,
+      operation,
+      description
+    });
+  }
+}
+class PluginStorageError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      pluginSlug = "unknown",
+      key = "",
+      operation = "unknown",
+      ...rest
+    } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Plugin Storage Error
+
+Plugin: ${pluginSlug}
+Key: ${key}
+Operation: ${operation}
+
+Possible causes:
+1. Storage not initialized (plugin not installed)
+2. Invalid key format
+3. S3 operation failed
+4. Permissions issue
+
+Solution:
+Ensure plugin has access to storage and key is valid.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/README.md#plugin-storage
+`.trim();
+    }
+    super(message, {
+      ...rest,
+      pluginSlug,
+      key,
+      operation,
+      description
+    });
+  }
+}
+class PartitionDriverError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      driver = "unknown",
+      operation = "unknown",
+      queueSize,
+      maxQueueSize,
+      ...rest
+    } = details;
+    let description = details.description;
+    if (!description && queueSize !== void 0 && maxQueueSize !== void 0) {
+      description = `
+Partition Driver Error
+
+Driver: ${driver}
+Operation: ${operation}
+Queue Status: ${queueSize}/${maxQueueSize}
+
+Possible causes:
+1. Queue is full (backpressure)
+2. Driver not properly configured
+3. SQS permissions issue (if using SQS driver)
+
+Solution:
+${queueSize >= maxQueueSize ? "Wait for queue to drain or increase maxQueueSize" : "Check driver configuration and permissions"}
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#partition-drivers
+`.trim();
+    } else if (!description) {
+      description = `
+Partition Driver Error
+
+Driver: ${driver}
+Operation: ${operation}
+
+Check driver configuration and permissions.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#partition-drivers
+`.trim();
+    }
+    super(message, {
+      ...rest,
+      driver,
+      operation,
+      queueSize,
+      maxQueueSize,
+      description
+    });
+  }
+}
+class BehaviorError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      behavior = "unknown",
+      availableBehaviors = [],
+      ...rest
+    } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Behavior Error
+
+Requested: ${behavior}
+Available: ${availableBehaviors.join(", ") || "body-overflow, body-only, truncate-data, enforce-limits, user-managed"}
+
+Possible causes:
+1. Behavior name misspelled
+2. Custom behavior not registered
+
+Solution:
+Use one of the available behaviors or register custom behavior.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#behaviors
+`.trim();
+    }
+    super(message, {
+      ...rest,
+      behavior,
+      availableBehaviors,
+      description
+    });
+  }
+}
+class StreamError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      operation = "unknown",
+      resource,
+      ...rest
+    } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Stream Error
+
+Operation: ${operation}
+${resource ? `Resource: ${resource}` : ""}
+
+Possible causes:
+1. Stream not properly initialized
+2. Resource not available
+3. Network error during streaming
+
+Solution:
+Check stream configuration and resource availability.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#streaming
+`.trim();
+    }
+    super(message, {
+      ...rest,
+      operation,
+      resource,
+      description
+    });
+  }
+}
+class MetadataLimitError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      totalSize,
+      effectiveLimit,
+      absoluteLimit = 2047,
+      excess,
+      resourceName,
+      operation,
+      ...rest
+    } = details;
+    let description = details.description;
+    if (!description && totalSize && effectiveLimit) {
+      description = `
+S3 Metadata Size Limit Exceeded
+
+Current Size: ${totalSize} bytes
+Effective Limit: ${effectiveLimit} bytes
+Absolute Limit: ${absoluteLimit} bytes
+${excess ? `Excess: ${excess} bytes` : ""}
+${resourceName ? `Resource: ${resourceName}` : ""}
+${operation ? `Operation: ${operation}` : ""}
+
+S3 has a hard limit of 2KB (2047 bytes) for object metadata.
+
+Solutions:
+1. Use 'body-overflow' behavior to store excess in body
+2. Use 'body-only' behavior to store everything in body
+3. Reduce number of fields
+4. Use shorter field values
+5. Enable advanced metadata encoding
+
+Example:
+  await db.createResource({
+    name: '${resourceName || "myResource"}',
+    behavior: 'body-overflow',  // Automatically handles overflow
+    attributes: { ... }
+  });
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#metadata-size-limits
+`.trim();
+    }
+    super(message, {
+      ...rest,
+      totalSize,
+      effectiveLimit,
+      absoluteLimit,
+      excess,
+      resourceName,
+      operation,
+      description
     });
   }
 }
@@ -902,10 +1155,17 @@ class PluginStorage {
    */
   constructor(client, pluginSlug) {
     if (!client) {
-      throw new Error("PluginStorage requires a client instance");
+      throw new PluginStorageError("PluginStorage requires a client instance", {
+        operation: "constructor",
+        pluginSlug,
+        suggestion: "Pass a valid S3db Client instance when creating PluginStorage"
+      });
     }
     if (!pluginSlug) {
-      throw new Error("PluginStorage requires a pluginSlug");
+      throw new PluginStorageError("PluginStorage requires a pluginSlug", {
+        operation: "constructor",
+        suggestion: 'Provide a plugin slug (e.g., "eventual-consistency", "cache", "audit")'
+      });
     }
     this.client = client;
     this.pluginSlug = pluginSlug;
@@ -958,7 +1218,15 @@ class PluginStorage {
     }
     const [ok, err] = await tryFn(() => this.client.putObject(putParams));
     if (!ok) {
-      throw new Error(`PluginStorage.set failed for key ${key}: ${err.message}`);
+      throw new PluginStorageError(`Failed to save plugin data`, {
+        pluginSlug: this.pluginSlug,
+        key,
+        operation: "set",
+        behavior,
+        ttl,
+        original: err,
+        suggestion: "Check S3 permissions and key format"
+      });
     }
   }
   /**
@@ -980,7 +1248,13 @@ class PluginStorage {
       if (err.name === "NoSuchKey" || err.Code === "NoSuchKey") {
         return null;
       }
-      throw new Error(`PluginStorage.get failed for key ${key}: ${err.message}`);
+      throw new PluginStorageError(`Failed to retrieve plugin data`, {
+        pluginSlug: this.pluginSlug,
+        key,
+        operation: "get",
+        original: err,
+        suggestion: "Check if the key exists and S3 permissions are correct"
+      });
     }
     const metadata = response.Metadata || {};
     const parsedMetadata = this._parseMetadataValues(metadata);
@@ -993,7 +1267,13 @@ class PluginStorage {
           data = { ...parsedMetadata, ...body };
         }
       } catch (parseErr) {
-        throw new Error(`PluginStorage.get failed to parse body for key ${key}: ${parseErr.message}`);
+        throw new PluginStorageError(`Failed to parse JSON body`, {
+          pluginSlug: this.pluginSlug,
+          key,
+          operation: "get",
+          original: parseErr,
+          suggestion: "Body content may be corrupted. Check S3 object integrity"
+        });
       }
     }
     const expiresAt = data._expiresat || data._expiresAt;
@@ -1054,7 +1334,15 @@ class PluginStorage {
       () => this.client.listObjects({ prefix: fullPrefix, maxKeys: limit })
     );
     if (!ok) {
-      throw new Error(`PluginStorage.list failed: ${err.message}`);
+      throw new PluginStorageError(`Failed to list plugin data`, {
+        pluginSlug: this.pluginSlug,
+        operation: "list",
+        prefix,
+        fullPrefix,
+        limit,
+        original: err,
+        suggestion: "Check S3 permissions and bucket configuration"
+      });
     }
     const keys = result.Contents?.map((item) => item.Key) || [];
     return this._removeKeyPrefix(keys);
@@ -1074,7 +1362,16 @@ class PluginStorage {
       () => this.client.listObjects({ prefix: fullPrefix, maxKeys: limit })
     );
     if (!ok) {
-      throw new Error(`PluginStorage.listForResource failed: ${err.message}`);
+      throw new PluginStorageError(`Failed to list resource data`, {
+        pluginSlug: this.pluginSlug,
+        operation: "listForResource",
+        resourceName,
+        subPrefix,
+        fullPrefix,
+        limit,
+        original: err,
+        suggestion: "Check resource name and S3 permissions"
+      });
     }
     const keys = result.Contents?.map((item) => item.Key) || [];
     return this._removeKeyPrefix(keys);
@@ -1214,7 +1511,13 @@ class PluginStorage {
   async delete(key) {
     const [ok, err] = await tryFn(() => this.client.deleteObject(key));
     if (!ok) {
-      throw new Error(`PluginStorage.delete failed for key ${key}: ${err.message}`);
+      throw new PluginStorageError(`Failed to delete plugin data`, {
+        pluginSlug: this.pluginSlug,
+        key,
+        operation: "delete",
+        original: err,
+        suggestion: "Check S3 delete permissions"
+      });
     }
   }
   /**
@@ -1401,16 +1704,28 @@ class PluginStorage {
           const valueSize = calculateUTF8Bytes(encoded);
           currentSize += keySize + valueSize;
           if (currentSize > effectiveLimit) {
-            throw new Error(
-              `Data exceeds metadata limit (${currentSize} > ${effectiveLimit} bytes). Use 'body-overflow' or 'body-only' behavior.`
-            );
+            throw new MetadataLimitError(`Data exceeds metadata limit with enforce-limits behavior`, {
+              totalSize: currentSize,
+              effectiveLimit,
+              absoluteLimit: S3_METADATA_LIMIT,
+              excess: currentSize - effectiveLimit,
+              operation: "PluginStorage.set",
+              pluginSlug: this.pluginSlug,
+              suggestion: "Use 'body-overflow' or 'body-only' behavior to handle large data"
+            });
           }
           metadata[key] = jsonValue;
         }
         break;
       }
       default:
-        throw new Error(`Unknown behavior: ${behavior}. Use 'body-overflow', 'body-only', or 'enforce-limits'.`);
+        throw new BehaviorError(`Unknown behavior: ${behavior}`, {
+          behavior,
+          availableBehaviors: ["body-overflow", "body-only", "enforce-limits"],
+          operation: "PluginStorage._applyBehavior",
+          pluginSlug: this.pluginSlug,
+          suggestion: "Use 'body-overflow', 'body-only', or 'enforce-limits'"
+        });
     }
     return { metadata, body };
   }
@@ -1975,6 +2290,35 @@ class AuditPlugin extends Plugin {
   }
 }
 
+class BackupError extends S3dbError {
+  constructor(message, details = {}) {
+    const { driver = "unknown", operation = "unknown", backupId, ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Backup Operation Error
+
+Driver: ${driver}
+Operation: ${operation}
+${backupId ? `Backup ID: ${backupId}` : ""}
+
+Common causes:
+1. Invalid backup driver configuration
+2. Destination storage not accessible
+3. Insufficient permissions
+4. Network connectivity issues
+5. Invalid backup file format
+
+Solution:
+Check driver configuration and ensure destination storage is accessible.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/backup.md
+`.trim();
+    }
+    super(message, { ...rest, driver, operation, backupId, description });
+  }
+}
+
 class BaseBackupDriver {
   constructor(config = {}) {
     this.config = {
@@ -2005,7 +2349,12 @@ class BaseBackupDriver {
    * @returns {Object} Upload result with destination info
    */
   async upload(filePath, backupId, manifest) {
-    throw new Error("upload() method must be implemented by subclass");
+    throw new BackupError("upload() method must be implemented by subclass", {
+      operation: "upload",
+      driver: this.constructor.name,
+      backupId,
+      suggestion: "Extend BaseBackupDriver and implement the upload() method"
+    });
   }
   /**
    * Download a backup file from the destination
@@ -2015,7 +2364,12 @@ class BaseBackupDriver {
    * @returns {string} Path to downloaded file
    */
   async download(backupId, targetPath, metadata) {
-    throw new Error("download() method must be implemented by subclass");
+    throw new BackupError("download() method must be implemented by subclass", {
+      operation: "download",
+      driver: this.constructor.name,
+      backupId,
+      suggestion: "Extend BaseBackupDriver and implement the download() method"
+    });
   }
   /**
    * Delete a backup from the destination
@@ -2023,7 +2377,12 @@ class BaseBackupDriver {
    * @param {Object} metadata - Backup metadata
    */
   async delete(backupId, metadata) {
-    throw new Error("delete() method must be implemented by subclass");
+    throw new BackupError("delete() method must be implemented by subclass", {
+      operation: "delete",
+      driver: this.constructor.name,
+      backupId,
+      suggestion: "Extend BaseBackupDriver and implement the delete() method"
+    });
   }
   /**
    * List backups available in the destination
@@ -2031,7 +2390,11 @@ class BaseBackupDriver {
    * @returns {Array} List of backup metadata
    */
   async list(options = {}) {
-    throw new Error("list() method must be implemented by subclass");
+    throw new BackupError("list() method must be implemented by subclass", {
+      operation: "list",
+      driver: this.constructor.name,
+      suggestion: "Extend BaseBackupDriver and implement the list() method"
+    });
   }
   /**
    * Verify backup integrity
@@ -2041,14 +2404,23 @@ class BaseBackupDriver {
    * @returns {boolean} True if backup is valid
    */
   async verify(backupId, expectedChecksum, metadata) {
-    throw new Error("verify() method must be implemented by subclass");
+    throw new BackupError("verify() method must be implemented by subclass", {
+      operation: "verify",
+      driver: this.constructor.name,
+      backupId,
+      suggestion: "Extend BaseBackupDriver and implement the verify() method"
+    });
   }
   /**
    * Get driver type identifier
    * @returns {string} Driver type
    */
   getType() {
-    throw new Error("getType() method must be implemented by subclass");
+    throw new BackupError("getType() method must be implemented by subclass", {
+      operation: "getType",
+      driver: this.constructor.name,
+      suggestion: "Extend BaseBackupDriver and implement the getType() method"
+    });
   }
   /**
    * Get driver-specific storage info
@@ -2090,7 +2462,11 @@ class FilesystemBackupDriver extends BaseBackupDriver {
   }
   async onSetup() {
     if (!this.config.path) {
-      throw new Error("FilesystemBackupDriver: path configuration is required");
+      throw new BackupError("FilesystemBackupDriver: path configuration is required", {
+        operation: "onSetup",
+        driver: "filesystem",
+        suggestion: 'Provide a path in config: new FilesystemBackupDriver({ path: "/path/to/backups" })'
+      });
     }
     this.log(`Initialized with path: ${this.config.path}`);
   }
@@ -2114,11 +2490,26 @@ class FilesystemBackupDriver extends BaseBackupDriver {
       () => promises.mkdir(targetDir, { recursive: true, mode: this.config.directoryPermissions })
     );
     if (!createDirOk) {
-      throw new Error(`Failed to create backup directory: ${createDirErr.message}`);
+      throw new BackupError("Failed to create backup directory", {
+        operation: "upload",
+        driver: "filesystem",
+        backupId,
+        targetDir,
+        original: createDirErr,
+        suggestion: "Check directory permissions and disk space"
+      });
     }
     const [copyOk, copyErr] = await tryFn(() => promises.copyFile(filePath, targetPath));
     if (!copyOk) {
-      throw new Error(`Failed to copy backup file: ${copyErr.message}`);
+      throw new BackupError("Failed to copy backup file", {
+        operation: "upload",
+        driver: "filesystem",
+        backupId,
+        filePath,
+        targetPath,
+        original: copyErr,
+        suggestion: "Check file permissions and disk space"
+      });
     }
     const [manifestOk, manifestErr] = await tryFn(
       () => import('fs/promises').then((fs) => fs.writeFile(
@@ -2129,7 +2520,14 @@ class FilesystemBackupDriver extends BaseBackupDriver {
     );
     if (!manifestOk) {
       await tryFn(() => promises.unlink(targetPath));
-      throw new Error(`Failed to write manifest: ${manifestErr.message}`);
+      throw new BackupError("Failed to write manifest file", {
+        operation: "upload",
+        driver: "filesystem",
+        backupId,
+        manifestPath,
+        original: manifestErr,
+        suggestion: "Check directory permissions and disk space"
+      });
     }
     const [statOk, , stats] = await tryFn(() => promises.stat(targetPath));
     const size = statOk ? stats.size : 0;
@@ -2148,13 +2546,27 @@ class FilesystemBackupDriver extends BaseBackupDriver {
     );
     const [existsOk] = await tryFn(() => promises.access(sourcePath));
     if (!existsOk) {
-      throw new Error(`Backup file not found: ${sourcePath}`);
+      throw new BackupError("Backup file not found", {
+        operation: "download",
+        driver: "filesystem",
+        backupId,
+        sourcePath,
+        suggestion: "Check if backup exists using list() method"
+      });
     }
     const targetDir = path.dirname(targetPath);
     await tryFn(() => promises.mkdir(targetDir, { recursive: true }));
     const [copyOk, copyErr] = await tryFn(() => promises.copyFile(sourcePath, targetPath));
     if (!copyOk) {
-      throw new Error(`Failed to download backup: ${copyErr.message}`);
+      throw new BackupError("Failed to download backup", {
+        operation: "download",
+        driver: "filesystem",
+        backupId,
+        sourcePath,
+        targetPath,
+        original: copyErr,
+        suggestion: "Check file permissions and disk space"
+      });
     }
     this.log(`Downloaded backup ${backupId} from ${sourcePath} to ${targetPath}`);
     return targetPath;
@@ -2171,7 +2583,14 @@ class FilesystemBackupDriver extends BaseBackupDriver {
     const [deleteBackupOk] = await tryFn(() => promises.unlink(backupPath));
     const [deleteManifestOk] = await tryFn(() => promises.unlink(manifestPath));
     if (!deleteBackupOk && !deleteManifestOk) {
-      throw new Error(`Failed to delete backup files for ${backupId}`);
+      throw new BackupError("Failed to delete backup files", {
+        operation: "delete",
+        driver: "filesystem",
+        backupId,
+        backupPath,
+        manifestPath,
+        suggestion: "Check file permissions"
+      });
     }
     this.log(`Deleted backup ${backupId}`);
   }
@@ -2276,10 +2695,18 @@ class S3BackupDriver extends BaseBackupDriver {
       this.config.bucket = this.database.bucket;
     }
     if (!this.config.client) {
-      throw new Error("S3BackupDriver: client is required (either via config or database)");
+      throw new BackupError("S3BackupDriver: client is required", {
+        operation: "onSetup",
+        driver: "s3",
+        suggestion: "Provide a client in config or ensure database has a client configured"
+      });
     }
     if (!this.config.bucket) {
-      throw new Error("S3BackupDriver: bucket is required (either via config or database)");
+      throw new BackupError("S3BackupDriver: bucket is required", {
+        operation: "onSetup",
+        driver: "s3",
+        suggestion: "Provide a bucket in config or ensure database has a bucket configured"
+      });
     }
     this.log(`Initialized with bucket: ${this.config.bucket}, path: ${this.config.path}`);
   }
@@ -2321,7 +2748,15 @@ class S3BackupDriver extends BaseBackupDriver {
       });
     });
     if (!uploadOk) {
-      throw new Error(`Failed to upload backup file: ${uploadErr.message}`);
+      throw new BackupError("Failed to upload backup file to S3", {
+        operation: "upload",
+        driver: "s3",
+        backupId,
+        bucket: this.config.bucket,
+        key: backupKey,
+        original: uploadErr,
+        suggestion: "Check S3 permissions and bucket configuration"
+      });
     }
     const [manifestOk, manifestErr] = await tryFn(
       () => this.config.client.uploadObject({
@@ -2342,7 +2777,15 @@ class S3BackupDriver extends BaseBackupDriver {
         bucket: this.config.bucket,
         key: backupKey
       }));
-      throw new Error(`Failed to upload manifest: ${manifestErr.message}`);
+      throw new BackupError("Failed to upload manifest to S3", {
+        operation: "upload",
+        driver: "s3",
+        backupId,
+        bucket: this.config.bucket,
+        manifestKey,
+        original: manifestErr,
+        suggestion: "Check S3 permissions and bucket configuration"
+      });
     }
     this.log(`Uploaded backup ${backupId} to s3://${this.config.bucket}/${backupKey} (${fileSize} bytes)`);
     return {
@@ -2365,7 +2808,16 @@ class S3BackupDriver extends BaseBackupDriver {
       })
     );
     if (!downloadOk) {
-      throw new Error(`Failed to download backup: ${downloadErr.message}`);
+      throw new BackupError("Failed to download backup from S3", {
+        operation: "download",
+        driver: "s3",
+        backupId,
+        bucket: this.config.bucket,
+        key: backupKey,
+        targetPath,
+        original: downloadErr,
+        suggestion: "Check if backup exists and S3 permissions are correct"
+      });
     }
     this.log(`Downloaded backup ${backupId} from s3://${this.config.bucket}/${backupKey} to ${targetPath}`);
     return targetPath;
@@ -2386,7 +2838,15 @@ class S3BackupDriver extends BaseBackupDriver {
       })
     );
     if (!deleteBackupOk && !deleteManifestOk) {
-      throw new Error(`Failed to delete backup objects for ${backupId}`);
+      throw new BackupError("Failed to delete backup from S3", {
+        operation: "delete",
+        driver: "s3",
+        backupId,
+        bucket: this.config.bucket,
+        backupKey,
+        manifestKey,
+        suggestion: "Check S3 delete permissions"
+      });
     }
     this.log(`Deleted backup ${backupId} from S3`);
   }
@@ -2499,11 +2959,22 @@ class MultiBackupDriver extends BaseBackupDriver {
   }
   async onSetup() {
     if (!Array.isArray(this.config.destinations) || this.config.destinations.length === 0) {
-      throw new Error("MultiBackupDriver: destinations array is required and must not be empty");
+      throw new BackupError("MultiBackupDriver requires non-empty destinations array", {
+        operation: "onSetup",
+        driver: "multi",
+        destinationsProvided: this.config.destinations,
+        suggestion: 'Provide destinations array: { destinations: [{ driver: "s3", config: {...} }, { driver: "filesystem", config: {...} }] }'
+      });
     }
     for (const [index, destConfig] of this.config.destinations.entries()) {
       if (!destConfig.driver) {
-        throw new Error(`MultiBackupDriver: destination[${index}] must have a driver type`);
+        throw new BackupError(`Destination ${index} missing driver type`, {
+          operation: "onSetup",
+          driver: "multi",
+          destinationIndex: index,
+          destination: destConfig,
+          suggestion: 'Each destination must have a driver property: { driver: "s3", config: {...} } or { driver: "filesystem", config: {...} }'
+        });
       }
       try {
         const driver = createBackupDriver(destConfig.driver, destConfig.config || {});
@@ -2515,7 +2986,15 @@ class MultiBackupDriver extends BaseBackupDriver {
         });
         this.log(`Setup destination ${index}: ${destConfig.driver}`);
       } catch (error) {
-        throw new Error(`Failed to setup destination ${index} (${destConfig.driver}): ${error.message}`);
+        throw new BackupError(`Failed to setup destination ${index}`, {
+          operation: "onSetup",
+          driver: "multi",
+          destinationIndex: index,
+          destinationDriver: destConfig.driver,
+          destinationConfig: destConfig.config,
+          original: error,
+          suggestion: "Check destination driver configuration and ensure dependencies are available"
+        });
       }
     }
     if (this.config.requireAll === false) {
@@ -2544,7 +3023,15 @@ class MultiBackupDriver extends BaseBackupDriver {
           this.log(`Priority upload failed to destination ${index}: ${err.message}`);
         }
       }
-      throw new Error(`All priority destinations failed: ${errors.map((e) => `${e.destination}: ${e.error}`).join("; ")}`);
+      throw new BackupError("All priority destinations failed", {
+        operation: "upload",
+        driver: "multi",
+        strategy: "priority",
+        backupId,
+        totalDestinations: this.drivers.length,
+        failures: errors,
+        suggestion: "Check destination configurations and ensure at least one destination is accessible"
+      });
     }
     const uploadPromises = this.drivers.map(async ({ driver, config, index }) => {
       const [ok, err, result] = await tryFn(
@@ -2574,10 +3061,28 @@ class MultiBackupDriver extends BaseBackupDriver {
     const successResults = allResults.filter((r) => r.status === "success");
     const failedResults = allResults.filter((r) => r.status === "failed");
     if (strategy === "all" && failedResults.length > 0) {
-      throw new Error(`Some destinations failed: ${failedResults.map((r) => `${r.destination}: ${r.error}`).join("; ")}`);
+      throw new BackupError('Some destinations failed with strategy "all"', {
+        operation: "upload",
+        driver: "multi",
+        strategy: "all",
+        backupId,
+        totalDestinations: this.drivers.length,
+        successCount: successResults.length,
+        failedCount: failedResults.length,
+        failures: failedResults,
+        suggestion: 'All destinations must succeed with "all" strategy. Use "any" strategy to tolerate failures, or fix failing destinations.'
+      });
     }
     if (strategy === "any" && successResults.length === 0) {
-      throw new Error(`All destinations failed: ${failedResults.map((r) => `${r.destination}: ${r.error}`).join("; ")}`);
+      throw new BackupError('All destinations failed with strategy "any"', {
+        operation: "upload",
+        driver: "multi",
+        strategy: "any",
+        backupId,
+        totalDestinations: this.drivers.length,
+        failures: failedResults,
+        suggestion: 'At least one destination must succeed with "any" strategy. Check all destination configurations.'
+      });
     }
     return allResults;
   }
@@ -2597,7 +3102,14 @@ class MultiBackupDriver extends BaseBackupDriver {
         this.log(`Download failed from destination ${destMetadata.destination}: ${err.message}`);
       }
     }
-    throw new Error(`Failed to download backup from any destination`);
+    throw new BackupError("Failed to download backup from any destination", {
+      operation: "download",
+      driver: "multi",
+      backupId,
+      targetPath,
+      attemptedDestinations: destinations.length,
+      suggestion: "Check if backup exists in at least one destination and destinations are accessible"
+    });
   }
   async delete(backupId, metadata) {
     const destinations = Array.isArray(metadata.destinations) ? metadata.destinations : [metadata];
@@ -2619,7 +3131,14 @@ class MultiBackupDriver extends BaseBackupDriver {
       }
     }
     if (successCount === 0 && errors.length > 0) {
-      throw new Error(`Failed to delete from any destination: ${errors.join("; ")}`);
+      throw new BackupError("Failed to delete from any destination", {
+        operation: "delete",
+        driver: "multi",
+        backupId,
+        attemptedDestinations: destinations.length,
+        failures: errors,
+        suggestion: "Check if backup exists in destinations and destinations are accessible with delete permissions"
+      });
     }
     if (errors.length > 0) {
       this.log(`Partial delete success, some errors: ${errors.join("; ")}`);
@@ -2719,32 +3238,62 @@ const BACKUP_DRIVERS = {
 function createBackupDriver(driver, config = {}) {
   const DriverClass = BACKUP_DRIVERS[driver];
   if (!DriverClass) {
-    throw new Error(`Unknown backup driver: ${driver}. Available drivers: ${Object.keys(BACKUP_DRIVERS).join(", ")}`);
+    throw new BackupError(`Unknown backup driver: ${driver}`, {
+      operation: "createBackupDriver",
+      driver,
+      availableDrivers: Object.keys(BACKUP_DRIVERS),
+      suggestion: `Use one of the available drivers: ${Object.keys(BACKUP_DRIVERS).join(", ")}`
+    });
   }
   return new DriverClass(config);
 }
 function validateBackupConfig(driver, config = {}) {
   if (!driver || typeof driver !== "string") {
-    throw new Error("Driver type must be a non-empty string");
+    throw new BackupError("Driver type must be a non-empty string", {
+      operation: "validateBackupConfig",
+      driver,
+      suggestion: "Provide a valid driver type string (filesystem, s3, or multi)"
+    });
   }
   if (!BACKUP_DRIVERS[driver]) {
-    throw new Error(`Unknown backup driver: ${driver}. Available drivers: ${Object.keys(BACKUP_DRIVERS).join(", ")}`);
+    throw new BackupError(`Unknown backup driver: ${driver}`, {
+      operation: "validateBackupConfig",
+      driver,
+      availableDrivers: Object.keys(BACKUP_DRIVERS),
+      suggestion: `Use one of the available drivers: ${Object.keys(BACKUP_DRIVERS).join(", ")}`
+    });
   }
   switch (driver) {
     case "filesystem":
       if (!config.path) {
-        throw new Error('FilesystemBackupDriver requires "path" configuration');
+        throw new BackupError('FilesystemBackupDriver requires "path" configuration', {
+          operation: "validateBackupConfig",
+          driver: "filesystem",
+          config,
+          suggestion: 'Provide a "path" property in config: { path: "/path/to/backups" }'
+        });
       }
       break;
     case "s3":
       break;
     case "multi":
       if (!Array.isArray(config.destinations) || config.destinations.length === 0) {
-        throw new Error('MultiBackupDriver requires non-empty "destinations" array');
+        throw new BackupError('MultiBackupDriver requires non-empty "destinations" array', {
+          operation: "validateBackupConfig",
+          driver: "multi",
+          config,
+          suggestion: 'Provide destinations array: { destinations: [{ driver: "s3", config: {...} }] }'
+        });
       }
       config.destinations.forEach((dest, index) => {
         if (!dest.driver) {
-          throw new Error(`Destination ${index} must have a "driver" property`);
+          throw new BackupError(`Destination ${index} must have a "driver" property`, {
+            operation: "validateBackupConfig",
+            driver: "multi",
+            destinationIndex: index,
+            destination: dest,
+            suggestion: 'Each destination must have a driver property: { driver: "s3", config: {...} }'
+          });
         }
         if (dest.driver !== "multi") {
           validateBackupConfig(dest.driver, dest.config || {});
@@ -3400,6 +3949,36 @@ class BackupPlugin extends Plugin {
   }
 }
 
+class CacheError extends S3dbError {
+  constructor(message, details = {}) {
+    const { driver = "unknown", operation = "unknown", resourceName, key, ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Cache Operation Error
+
+Driver: ${driver}
+Operation: ${operation}
+${resourceName ? `Resource: ${resourceName}` : ""}
+${key ? `Key: ${key}` : ""}
+
+Common causes:
+1. Invalid cache key format
+2. Cache driver not properly initialized
+3. Resource not found or not cached
+4. Memory limits exceeded
+5. Filesystem permissions issues
+
+Solution:
+Check cache configuration and ensure the cache driver is properly initialized.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/cache.md
+`.trim();
+    }
+    super(message, { ...rest, driver, operation, resourceName, key, description });
+  }
+}
+
 class Cache extends EventEmitter {
   constructor(config = {}) {
     super();
@@ -3416,7 +3995,13 @@ class Cache extends EventEmitter {
   }
   validateKey(key) {
     if (key === null || key === void 0 || typeof key !== "string" || !key) {
-      throw new Error("Invalid key");
+      throw new CacheError("Invalid cache key", {
+        operation: "validateKey",
+        driver: this.constructor.name,
+        key,
+        keyType: typeof key,
+        suggestion: "Cache key must be a non-empty string"
+      });
     }
   }
   // generic class methods
@@ -3503,7 +4088,11 @@ class ResourceReader extends EventEmitter {
   constructor({ resource, batchSize = 10, concurrency = 5 }) {
     super();
     if (!resource) {
-      throw new Error("Resource is required for ResourceReader");
+      throw new StreamError("Resource is required for ResourceReader", {
+        operation: "constructor",
+        resource: resource?.name,
+        suggestion: "Pass a valid Resource instance when creating ResourceReader"
+      });
     }
     this.resource = resource;
     this.client = resource.client;
@@ -3627,7 +4216,10 @@ class ResourceWriter extends EventEmitter {
 function streamToString(stream) {
   return new Promise((resolve, reject) => {
     if (!stream) {
-      return reject(new Error("streamToString: stream is undefined"));
+      return reject(new StreamError("Stream is undefined", {
+        operation: "streamToString",
+        suggestion: "Ensure a valid stream is passed to streamToString()"
+      }));
     }
     const chunks = [];
     stream.on("data", (chunk) => chunks.push(chunk));
@@ -5121,7 +5713,13 @@ class CachePlugin extends Plugin {
   async warmCache(resourceName, options = {}) {
     const resource = this.database.resources[resourceName];
     if (!resource) {
-      throw new Error(`Resource '${resourceName}' not found`);
+      throw new CacheError("Resource not found for cache warming", {
+        operation: "warmCache",
+        driver: this.driver?.constructor.name,
+        resourceName,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: "Check resource name spelling or ensure resource has been created"
+      });
     }
     const { includePartitions = true, sampleSize = 100 } = options;
     if (this.driver instanceof PartitionAwareFilesystemCache && resource.warmPartitionCache) {
@@ -8238,6 +8836,35 @@ class EventualConsistencyPlugin extends Plugin {
   }
 }
 
+class FulltextError extends S3dbError {
+  constructor(message, details = {}) {
+    const { resourceName, query, operation = "unknown", ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Fulltext Search Operation Error
+
+Operation: ${operation}
+${resourceName ? `Resource: ${resourceName}` : ""}
+${query ? `Query: ${query}` : ""}
+
+Common causes:
+1. Resource not indexed for fulltext search
+2. Invalid query syntax
+3. Index not built yet
+4. Search configuration missing
+5. Field not indexed
+
+Solution:
+Ensure resource is configured for fulltext search and index is built.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/fulltext.md
+`.trim();
+    }
+    super(message, { ...rest, resourceName, query, operation, description });
+  }
+}
+
 class FullTextPlugin extends Plugin {
   constructor(options = {}) {
     super();
@@ -8544,7 +9171,13 @@ class FullTextPlugin extends Plugin {
     }
     const resource = this.database.resources[resourceName];
     if (!resource) {
-      throw new Error(`Resource '${resourceName}' not found`);
+      throw new FulltextError(`Resource '${resourceName}' not found`, {
+        operation: "searchRecords",
+        resourceName,
+        query,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: "Check resource name or ensure resource is created before searching"
+      });
     }
     const recordIds = searchResults.map((result2) => result2.recordId);
     const records = await resource.getMany(recordIds);
@@ -8561,7 +9194,12 @@ class FullTextPlugin extends Plugin {
   async rebuildIndex(resourceName) {
     const resource = this.database.resources[resourceName];
     if (!resource) {
-      throw new Error(`Resource '${resourceName}' not found`);
+      throw new FulltextError(`Resource '${resourceName}' not found`, {
+        operation: "rebuildIndex",
+        resourceName,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: "Check resource name or ensure resource is created before rebuilding index"
+      });
     }
     for (const [key] of this.indexes.entries()) {
       if (key.startsWith(`${resourceName}:`)) {
@@ -9346,6 +9984,35 @@ function createConsumer(driver, config) {
   return new ConsumerClass(config);
 }
 
+class QueueError extends S3dbError {
+  constructor(message, details = {}) {
+    const { queueName, operation = "unknown", messageId, ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Queue Operation Error
+
+Operation: ${operation}
+${queueName ? `Queue: ${queueName}` : ""}
+${messageId ? `Message ID: ${messageId}` : ""}
+
+Common causes:
+1. Queue not properly configured
+2. Message handler not registered
+3. Queue resource not found
+4. SQS/RabbitMQ connection failed
+5. Message processing timeout
+
+Solution:
+Check queue configuration and message handler registration.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/queue.md
+`.trim();
+    }
+    super(message, { ...rest, queueName, operation, messageId, description });
+  }
+}
+
 class QueueConsumerPlugin extends Plugin {
   constructor(options = {}) {
     super(options);
@@ -9406,13 +10073,32 @@ class QueueConsumerPlugin extends Plugin {
     let action = body.action || msg.action;
     let data = body.data || msg.data;
     if (!resource) {
-      throw new Error("QueueConsumerPlugin: resource not found in message");
+      throw new QueueError("Resource not found in message", {
+        operation: "handleMessage",
+        queueName: configuredResource,
+        messageBody: body,
+        suggestion: 'Ensure message includes a "resource" field specifying the target resource name'
+      });
     }
     if (!action) {
-      throw new Error("QueueConsumerPlugin: action not found in message");
+      throw new QueueError("Action not found in message", {
+        operation: "handleMessage",
+        queueName: configuredResource,
+        resource,
+        messageBody: body,
+        suggestion: 'Ensure message includes an "action" field (insert, update, or delete)'
+      });
     }
     const resourceObj = this.database.resources[resource];
-    if (!resourceObj) throw new Error(`QueueConsumerPlugin: resource '${resource}' not found`);
+    if (!resourceObj) {
+      throw new QueueError(`Resource '${resource}' not found`, {
+        operation: "handleMessage",
+        queueName: configuredResource,
+        resource,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: "Check resource name or ensure resource is created before consuming messages"
+      });
+    }
     let result;
     const [ok, err, res] = await tryFn(async () => {
       if (action === "insert") {
@@ -9423,7 +10109,14 @@ class QueueConsumerPlugin extends Plugin {
       } else if (action === "delete") {
         result = await resourceObj.delete(data.id);
       } else {
-        throw new Error(`QueueConsumerPlugin: unsupported action '${action}'`);
+        throw new QueueError(`Unsupported action '${action}'`, {
+          operation: "handleMessage",
+          queueName: configuredResource,
+          resource,
+          action,
+          supportedActions: ["insert", "update", "delete"],
+          suggestion: "Use one of the supported actions: insert, update, or delete"
+        });
       }
       return result;
     });
@@ -9436,6 +10129,35 @@ class QueueConsumerPlugin extends Plugin {
   }
 }
 
+class ReplicationError extends S3dbError {
+  constructor(message, details = {}) {
+    const { replicatorClass = "unknown", operation = "unknown", resourceName, ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Replication Operation Error
+
+Replicator: ${replicatorClass}
+Operation: ${operation}
+${resourceName ? `Resource: ${resourceName}` : ""}
+
+Common causes:
+1. Invalid replicator configuration
+2. Target system not accessible
+3. Resource not configured for replication
+4. Invalid operation type
+5. Transformation function errors
+
+Solution:
+Check replicator configuration and ensure target system is accessible.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/replicator.md
+`.trim();
+    }
+    super(message, { ...rest, replicatorClass, operation, resourceName, description });
+  }
+}
+
 class BaseReplicator extends EventEmitter {
   constructor(config = {}) {
     super();
@@ -9461,7 +10183,12 @@ class BaseReplicator extends EventEmitter {
    * @returns {Promise<Object>} replicator result
    */
   async replicate(resourceName, operation, data, id) {
-    throw new Error(`replicate() method must be implemented by ${this.name}`);
+    throw new ReplicationError("replicate() method must be implemented by subclass", {
+      operation: "replicate",
+      replicatorClass: this.name,
+      resourceName,
+      suggestion: "Extend BaseReplicator and implement the replicate() method"
+    });
   }
   /**
    * Replicate multiple records in batch
@@ -9470,14 +10197,24 @@ class BaseReplicator extends EventEmitter {
    * @returns {Promise<Object>} Batch replicator result
    */
   async replicateBatch(resourceName, records) {
-    throw new Error(`replicateBatch() method must be implemented by ${this.name}`);
+    throw new ReplicationError("replicateBatch() method must be implemented by subclass", {
+      operation: "replicateBatch",
+      replicatorClass: this.name,
+      resourceName,
+      batchSize: records?.length,
+      suggestion: "Extend BaseReplicator and implement the replicateBatch() method"
+    });
   }
   /**
    * Test the connection to the target
    * @returns {Promise<boolean>} True if connection is successful
    */
   async testConnection() {
-    throw new Error(`testConnection() method must be implemented by ${this.name}`);
+    throw new ReplicationError("testConnection() method must be implemented by subclass", {
+      operation: "testConnection",
+      replicatorClass: this.name,
+      suggestion: "Extend BaseReplicator and implement the testConnection() method"
+    });
   }
   /**
    * Get replicator status and statistics
@@ -10649,7 +11386,17 @@ class Client extends EventEmitter {
     });
     this.emit("moveAllObjects", { results, errors }, { prefixFrom, prefixTo });
     if (errors.length > 0) {
-      throw new Error("Some objects could not be moved");
+      throw new UnknownError("Some objects could not be moved", {
+        bucket: this.config.bucket,
+        operation: "moveAllObjects",
+        prefixFrom,
+        prefixTo,
+        totalKeys: keys.length,
+        failedCount: errors.length,
+        successCount: results.length,
+        errors: errors.map((e) => ({ message: e.message, raw: e.raw })),
+        suggestion: "Check S3 permissions and retry failed objects individually"
+      });
     }
     return results;
   }
@@ -11363,7 +12110,14 @@ async function handleInsert$4({ resource, data, mappedData, originalData }) {
     }
   });
   if (totalSize > effectiveLimit) {
-    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, effective limit: ${effectiveLimit} bytes, absolute limit: ${S3_METADATA_LIMIT_BYTES} bytes`);
+    throw new MetadataLimitError("Metadata size exceeds 2KB limit on insert", {
+      totalSize,
+      effectiveLimit,
+      absoluteLimit: S3_METADATA_LIMIT_BYTES,
+      excess: totalSize - effectiveLimit,
+      resourceName: resource.name,
+      operation: "insert"
+    });
   }
   return { mappedData, body: "" };
 }
@@ -11378,7 +12132,15 @@ async function handleUpdate$4({ resource, id, data, mappedData, originalData })
     }
   });
   if (totalSize > effectiveLimit) {
-    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, effective limit: ${effectiveLimit} bytes, absolute limit: ${S3_METADATA_LIMIT_BYTES} bytes`);
+    throw new MetadataLimitError("Metadata size exceeds 2KB limit on update", {
+      totalSize,
+      effectiveLimit,
+      absoluteLimit: S3_METADATA_LIMIT_BYTES,
+      excess: totalSize - effectiveLimit,
+      resourceName: resource.name,
+      operation: "update",
+      id
+    });
   }
   return { mappedData, body: JSON.stringify(mappedData) };
 }
@@ -11393,7 +12155,15 @@ async function handleUpsert$4({ resource, id, data, mappedData }) {
     }
   });
   if (totalSize > effectiveLimit) {
-    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, effective limit: ${effectiveLimit} bytes, absolute limit: ${S3_METADATA_LIMIT_BYTES} bytes`);
+    throw new MetadataLimitError("Metadata size exceeds 2KB limit on upsert", {
+      totalSize,
+      effectiveLimit,
+      absoluteLimit: S3_METADATA_LIMIT_BYTES,
+      excess: totalSize - effectiveLimit,
+      resourceName: resource.name,
+      operation: "upsert",
+      id
+    });
   }
   return { mappedData, body: "" };
 }
@@ -11735,7 +12505,11 @@ const behaviors = {
 function getBehavior(behaviorName) {
   const behavior = behaviors[behaviorName];
   if (!behavior) {
-    throw new Error(`Unknown behavior: ${behaviorName}. Available behaviors: ${Object.keys(behaviors).join(", ")}`);
+    throw new BehaviorError(`Unknown behavior: ${behaviorName}`, {
+      behavior: behaviorName,
+      availableBehaviors: Object.keys(behaviors),
+      operation: "getBehavior"
+    });
   }
   return behavior;
 }
@@ -14259,7 +15033,7 @@ class Database extends EventEmitter {
     this.id = idGenerator(7);
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => true ? "11.2.3" : "latest");
+      const [ok, err, version] = tryFn(() => true ? "11.2.4" : "latest");
       return ok ? version : "latest";
     })();
     this.resources = {};
@@ -14604,7 +15378,12 @@ class Database extends EventEmitter {
     const pluginName = name.toLowerCase().replace("plugin", "");
     const plugin = this.plugins[pluginName] || this.pluginRegistry[pluginName];
     if (!plugin) {
-      throw new Error(`Plugin '${name}' not found`);
+      throw new DatabaseError(`Plugin '${name}' not found`, {
+        operation: "uninstallPlugin",
+        pluginName: name,
+        availablePlugins: Object.keys(this.pluginRegistry),
+        suggestion: "Check plugin name or list available plugins using Object.keys(db.pluginRegistry)"
+      });
     }
     if (plugin.stop) {
       await plugin.stop();
@@ -15237,10 +16016,20 @@ class Database extends EventEmitter {
   addHook(event, fn) {
     if (!this._hooks) this._initHooks();
     if (!this._hooks.has(event)) {
-      throw new Error(`Unknown hook event: ${event}. Available events: ${this._hookEvents.join(", ")}`);
+      throw new DatabaseError(`Unknown hook event: ${event}`, {
+        operation: "addHook",
+        invalidEvent: event,
+        availableEvents: this._hookEvents,
+        suggestion: `Use one of the available hook events: ${this._hookEvents.join(", ")}`
+      });
     }
     if (typeof fn !== "function") {
-      throw new Error("Hook function must be a function");
+      throw new DatabaseError("Hook function must be a function", {
+        operation: "addHook",
+        event,
+        receivedType: typeof fn,
+        suggestion: "Provide a function that will be called when the hook event occurs"
+      });
     }
     this._hooks.get(event).push(fn);
   }
@@ -15378,7 +16167,11 @@ class S3dbReplicator extends BaseReplicator {
         this.targetDatabase = new S3db(targetConfig);
         await this.targetDatabase.connect();
       } else {
-        throw new Error("S3dbReplicator: No client or connectionString provided");
+        throw new ReplicationError("S3dbReplicator requires client or connectionString", {
+          operation: "initialize",
+          replicatorClass: "S3dbReplicator",
+          suggestion: 'Provide either a client instance or connectionString in config: { client: db } or { connectionString: "s3://..." }'
+        });
       }
       this.emit("connected", {
         replicator: this.name,
@@ -15409,7 +16202,13 @@ class S3dbReplicator extends BaseReplicator {
     const normResource = normalizeResourceName$1(resource);
     const entry = this.resourcesMap[normResource];
     if (!entry) {
-      throw new Error(`[S3dbReplicator] Resource not configured: ${resource}`);
+      throw new ReplicationError("Resource not configured for replication", {
+        operation: "replicate",
+        replicatorClass: "S3dbReplicator",
+        resourceName: resource,
+        configuredResources: Object.keys(this.resourcesMap),
+        suggestion: 'Add resource to replicator resources map: { resources: { [resourceName]: "destination" } }'
+      });
     }
     if (Array.isArray(entry)) {
       const results = [];
@@ -15477,7 +16276,14 @@ class S3dbReplicator extends BaseReplicator {
     } else if (operation === "delete") {
       result = await destResourceObj.delete(recordId);
     } else {
-      throw new Error(`Invalid operation: ${operation}. Supported operations are: insert, update, delete`);
+      throw new ReplicationError(`Invalid replication operation: ${operation}`, {
+        operation: "replicate",
+        replicatorClass: "S3dbReplicator",
+        invalidOperation: operation,
+        supportedOperations: ["insert", "update", "delete"],
+        resourceName: sourceResource,
+        suggestion: "Use one of the supported operations: insert, update, delete"
+      });
     }
     return result;
   }
@@ -15545,7 +16351,13 @@ class S3dbReplicator extends BaseReplicator {
     const norm = normalizeResourceName$1(resource);
     const found = available.find((r) => normalizeResourceName$1(r) === norm);
     if (!found) {
-      throw new Error(`[S3dbReplicator] Destination resource not found: ${resource}. Available: ${available.join(", ")}`);
+      throw new ReplicationError("Destination resource not found in target database", {
+        operation: "_getDestResourceObj",
+        replicatorClass: "S3dbReplicator",
+        destinationResource: resource,
+        availableResources: available,
+        suggestion: "Create the resource in target database or check resource name spelling"
+      });
     }
     return db.resources[found];
   }
@@ -15594,7 +16406,13 @@ class S3dbReplicator extends BaseReplicator {
   }
   async testConnection() {
     const [ok, err] = await tryFn(async () => {
-      if (!this.targetDatabase) throw new Error("No target database configured");
+      if (!this.targetDatabase) {
+        throw new ReplicationError("No target database configured for connection test", {
+          operation: "testConnection",
+          replicatorClass: "S3dbReplicator",
+          suggestion: "Initialize replicator with client or connectionString before testing connection"
+        });
+      }
       if (typeof this.targetDatabase.connect === "function") {
         await this.targetDatabase.connect();
       }
@@ -15981,7 +16799,12 @@ const REPLICATOR_DRIVERS = {
 function createReplicator(driver, config = {}, resources = [], client = null) {
   const ReplicatorClass = REPLICATOR_DRIVERS[driver];
   if (!ReplicatorClass) {
-    throw new Error(`Unknown replicator driver: ${driver}. Available drivers: ${Object.keys(REPLICATOR_DRIVERS).join(", ")}`);
+    throw new ReplicationError(`Unknown replicator driver: ${driver}`, {
+      operation: "createReplicator",
+      driver,
+      availableDrivers: Object.keys(REPLICATOR_DRIVERS),
+      suggestion: `Use one of the available drivers: ${Object.keys(REPLICATOR_DRIVERS).join(", ")}`
+    });
   }
   return new ReplicatorClass(config, resources, client);
 }
@@ -15993,12 +16816,40 @@ class ReplicatorPlugin extends Plugin {
   constructor(options = {}) {
     super();
     if (!options.replicators || !Array.isArray(options.replicators)) {
-      throw new Error("ReplicatorPlugin: replicators array is required");
+      throw new ReplicationError("ReplicatorPlugin requires replicators array", {
+        operation: "constructor",
+        pluginName: "ReplicatorPlugin",
+        providedOptions: Object.keys(options),
+        suggestion: 'Provide replicators array: new ReplicatorPlugin({ replicators: [{ driver: "s3db", resources: [...] }] })'
+      });
     }
     for (const rep of options.replicators) {
-      if (!rep.driver) throw new Error("ReplicatorPlugin: each replicator must have a driver");
-      if (!rep.resources || typeof rep.resources !== "object") throw new Error("ReplicatorPlugin: each replicator must have resources config");
-      if (Object.keys(rep.resources).length === 0) throw new Error("ReplicatorPlugin: each replicator must have at least one resource configured");
+      if (!rep.driver) {
+        throw new ReplicationError("Each replicator must have a driver", {
+          operation: "constructor",
+          pluginName: "ReplicatorPlugin",
+          replicatorConfig: rep,
+          suggestion: 'Each replicator entry must specify a driver: { driver: "s3db", resources: {...} }'
+        });
+      }
+      if (!rep.resources || typeof rep.resources !== "object") {
+        throw new ReplicationError("Each replicator must have resources config", {
+          operation: "constructor",
+          pluginName: "ReplicatorPlugin",
+          driver: rep.driver,
+          replicatorConfig: rep,
+          suggestion: 'Provide resources as object or array: { driver: "s3db", resources: ["users"] } or { resources: { users: "people" } }'
+        });
+      }
+      if (Object.keys(rep.resources).length === 0) {
+        throw new ReplicationError("Each replicator must have at least one resource configured", {
+          operation: "constructor",
+          pluginName: "ReplicatorPlugin",
+          driver: rep.driver,
+          replicatorConfig: rep,
+          suggestion: 'Add at least one resource to replicate: { driver: "s3db", resources: ["users"] }'
+        });
+      }
     }
     this.config = {
       replicators: options.replicators || [],
@@ -16424,7 +17275,13 @@ class ReplicatorPlugin extends Plugin {
   async syncAllData(replicatorId) {
     const replicator = this.replicators.find((r) => r.id === replicatorId);
     if (!replicator) {
-      throw new Error(`Replicator not found: ${replicatorId}`);
+      throw new ReplicationError("Replicator not found", {
+        operation: "syncAllData",
+        pluginName: "ReplicatorPlugin",
+        replicatorId,
+        availableReplicators: this.replicators.map((r) => r.id),
+        suggestion: "Check replicator ID or use getReplicatorStats() to list available replicators"
+      });
     }
     this.stats.lastSync = (/* @__PURE__ */ new Date()).toISOString();
     for (const resourceName in this.database.resources) {
@@ -16954,6 +17811,35 @@ class S3QueuePlugin extends Plugin {
   }
 }
 
+class SchedulerError extends S3dbError {
+  constructor(message, details = {}) {
+    const { taskId, operation = "unknown", cronExpression, ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+Scheduler Operation Error
+
+Operation: ${operation}
+${taskId ? `Task ID: ${taskId}` : ""}
+${cronExpression ? `Cron: ${cronExpression}` : ""}
+
+Common causes:
+1. Invalid cron expression format
+2. Task not found or already exists
+3. Scheduler not properly initialized
+4. Job execution failure
+5. Resource conflicts
+
+Solution:
+Check task configuration and ensure scheduler is properly initialized.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/scheduler.md
+`.trim();
+    }
+    super(message, { ...rest, taskId, operation, cronExpression, description });
+  }
+}
+
 class SchedulerPlugin extends Plugin {
   constructor(options = {}) {
     super();
@@ -16987,17 +17873,36 @@ class SchedulerPlugin extends Plugin {
   }
   _validateConfiguration() {
     if (Object.keys(this.config.jobs).length === 0) {
-      throw new Error("SchedulerPlugin: At least one job must be defined");
+      throw new SchedulerError("At least one job must be defined", {
+        operation: "validateConfiguration",
+        jobCount: 0,
+        suggestion: 'Provide at least one job in the jobs configuration: { jobs: { myJob: { schedule: "* * * * *", action: async () => {...} } } }'
+      });
     }
     for (const [jobName, job] of Object.entries(this.config.jobs)) {
       if (!job.schedule) {
-        throw new Error(`SchedulerPlugin: Job '${jobName}' must have a schedule`);
+        throw new SchedulerError(`Job '${jobName}' must have a schedule`, {
+          operation: "validateConfiguration",
+          taskId: jobName,
+          providedConfig: Object.keys(job),
+          suggestion: 'Add a schedule property with a valid cron expression: { schedule: "0 * * * *", action: async () => {...} }'
+        });
       }
       if (!job.action || typeof job.action !== "function") {
-        throw new Error(`SchedulerPlugin: Job '${jobName}' must have an action function`);
+        throw new SchedulerError(`Job '${jobName}' must have an action function`, {
+          operation: "validateConfiguration",
+          taskId: jobName,
+          actionType: typeof job.action,
+          suggestion: 'Provide an action function: { schedule: "...", action: async (db, ctx) => {...} }'
+        });
       }
       if (!this._isValidCronExpression(job.schedule)) {
-        throw new Error(`SchedulerPlugin: Job '${jobName}' has invalid cron expression: ${job.schedule}`);
+        throw new SchedulerError(`Job '${jobName}' has invalid cron expression`, {
+          operation: "validateConfiguration",
+          taskId: jobName,
+          cronExpression: job.schedule,
+          suggestion: "Use valid cron format (5 fields: minute hour day month weekday) or shortcuts (@hourly, @daily, @weekly, @monthly, @yearly)"
+        });
       }
     }
   }
@@ -17295,10 +18200,20 @@ class SchedulerPlugin extends Plugin {
   async runJob(jobName, context = {}) {
     const job = this.jobs.get(jobName);
     if (!job) {
-      throw new Error(`Job '${jobName}' not found`);
+      throw new SchedulerError(`Job '${jobName}' not found`, {
+        operation: "runJob",
+        taskId: jobName,
+        availableJobs: Array.from(this.jobs.keys()),
+        suggestion: "Check job name or use getAllJobsStatus() to list available jobs"
+      });
     }
     if (this.activeJobs.has(jobName)) {
-      throw new Error(`Job '${jobName}' is already running`);
+      throw new SchedulerError(`Job '${jobName}' is already running`, {
+        operation: "runJob",
+        taskId: jobName,
+        executionId: this.activeJobs.get(jobName),
+        suggestion: "Wait for current execution to complete or check job status with getJobStatus()"
+      });
     }
     await this._executeJob(jobName);
   }
@@ -17308,7 +18223,12 @@ class SchedulerPlugin extends Plugin {
   enableJob(jobName) {
     const job = this.jobs.get(jobName);
     if (!job) {
-      throw new Error(`Job '${jobName}' not found`);
+      throw new SchedulerError(`Job '${jobName}' not found`, {
+        operation: "enableJob",
+        taskId: jobName,
+        availableJobs: Array.from(this.jobs.keys()),
+        suggestion: "Check job name or use getAllJobsStatus() to list available jobs"
+      });
     }
     job.enabled = true;
     this._scheduleNextExecution(jobName);
@@ -17320,7 +18240,12 @@ class SchedulerPlugin extends Plugin {
   disableJob(jobName) {
     const job = this.jobs.get(jobName);
     if (!job) {
-      throw new Error(`Job '${jobName}' not found`);
+      throw new SchedulerError(`Job '${jobName}' not found`, {
+        operation: "disableJob",
+        taskId: jobName,
+        availableJobs: Array.from(this.jobs.keys()),
+        suggestion: "Check job name or use getAllJobsStatus() to list available jobs"
+      });
     }
     job.enabled = false;
     const timer = this.timers.get(jobName);
@@ -17419,13 +18344,28 @@ class SchedulerPlugin extends Plugin {
    */
   addJob(jobName, jobConfig) {
     if (this.jobs.has(jobName)) {
-      throw new Error(`Job '${jobName}' already exists`);
+      throw new SchedulerError(`Job '${jobName}' already exists`, {
+        operation: "addJob",
+        taskId: jobName,
+        existingJobs: Array.from(this.jobs.keys()),
+        suggestion: "Use a different job name or remove the existing job first with removeJob()"
+      });
     }
     if (!jobConfig.schedule || !jobConfig.action) {
-      throw new Error("Job must have schedule and action");
+      throw new SchedulerError("Job must have schedule and action", {
+        operation: "addJob",
+        taskId: jobName,
+        providedConfig: Object.keys(jobConfig),
+        suggestion: 'Provide both schedule and action: { schedule: "0 * * * *", action: async (db, ctx) => {...} }'
+      });
     }
     if (!this._isValidCronExpression(jobConfig.schedule)) {
-      throw new Error(`Invalid cron expression: ${jobConfig.schedule}`);
+      throw new SchedulerError("Invalid cron expression", {
+        operation: "addJob",
+        taskId: jobName,
+        cronExpression: jobConfig.schedule,
+        suggestion: "Use valid cron format (5 fields) or shortcuts (@hourly, @daily, @weekly, @monthly, @yearly)"
+      });
     }
     const job = {
       ...jobConfig,
@@ -17459,7 +18399,12 @@ class SchedulerPlugin extends Plugin {
   removeJob(jobName) {
     const job = this.jobs.get(jobName);
     if (!job) {
-      throw new Error(`Job '${jobName}' not found`);
+      throw new SchedulerError(`Job '${jobName}' not found`, {
+        operation: "removeJob",
+        taskId: jobName,
+        availableJobs: Array.from(this.jobs.keys()),
+        suggestion: "Check job name or use getAllJobsStatus() to list available jobs"
+      });
     }
     const timer = this.timers.get(jobName);
     if (timer) {
@@ -17513,6 +18458,36 @@ class SchedulerPlugin extends Plugin {
   }
 }
 
+class StateMachineError extends S3dbError {
+  constructor(message, details = {}) {
+    const { currentState, targetState, resourceName, operation = "unknown", ...rest } = details;
+    let description = details.description;
+    if (!description) {
+      description = `
+State Machine Operation Error
+
+Operation: ${operation}
+${currentState ? `Current State: ${currentState}` : ""}
+${targetState ? `Target State: ${targetState}` : ""}
+${resourceName ? `Resource: ${resourceName}` : ""}
+
+Common causes:
+1. Invalid state transition
+2. State machine not configured
+3. Transition conditions not met
+4. State not defined in configuration
+5. Missing transition handler
+
+Solution:
+Check state machine configuration and valid transitions.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/state-machine.md
+`.trim();
+    }
+    super(message, { ...rest, currentState, targetState, resourceName, operation, description });
+  }
+}
+
 class StateMachinePlugin extends Plugin {
   constructor(options = {}) {
     super();
@@ -17533,17 +18508,36 @@ class StateMachinePlugin extends Plugin {
   }
   _validateConfiguration() {
     if (!this.config.stateMachines || Object.keys(this.config.stateMachines).length === 0) {
-      throw new Error("StateMachinePlugin: At least one state machine must be defined");
+      throw new StateMachineError("At least one state machine must be defined", {
+        operation: "validateConfiguration",
+        machineCount: 0,
+        suggestion: "Provide at least one state machine in the stateMachines configuration"
+      });
     }
     for (const [machineName, machine] of Object.entries(this.config.stateMachines)) {
       if (!machine.states || Object.keys(machine.states).length === 0) {
-        throw new Error(`StateMachinePlugin: Machine '${machineName}' must have states defined`);
+        throw new StateMachineError(`Machine '${machineName}' must have states defined`, {
+          operation: "validateConfiguration",
+          machineId: machineName,
+          suggestion: "Define at least one state in the states configuration"
+        });
       }
       if (!machine.initialState) {
-        throw new Error(`StateMachinePlugin: Machine '${machineName}' must have an initialState`);
+        throw new StateMachineError(`Machine '${machineName}' must have an initialState`, {
+          operation: "validateConfiguration",
+          machineId: machineName,
+          availableStates: Object.keys(machine.states),
+          suggestion: "Specify an initialState property matching one of the defined states"
+        });
       }
       if (!machine.states[machine.initialState]) {
-        throw new Error(`StateMachinePlugin: Initial state '${machine.initialState}' not found in machine '${machineName}'`);
+        throw new StateMachineError(`Initial state '${machine.initialState}' not found in machine '${machineName}'`, {
+          operation: "validateConfiguration",
+          machineId: machineName,
+          initialState: machine.initialState,
+          availableStates: Object.keys(machine.states),
+          suggestion: "Set initialState to one of the defined states"
+        });
       }
     }
   }
@@ -17600,12 +18594,25 @@ class StateMachinePlugin extends Plugin {
   async send(machineId, entityId, event, context = {}) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: "send",
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: "Check machine ID or use getMachines() to list available machines"
+      });
     }
     const currentState = await this.getState(machineId, entityId);
     const stateConfig = machine.config.states[currentState];
     if (!stateConfig || !stateConfig.on || !stateConfig.on[event]) {
-      throw new Error(`Event '${event}' not valid for state '${currentState}' in machine '${machineId}'`);
+      throw new StateMachineError(`Event '${event}' not valid for state '${currentState}' in machine '${machineId}'`, {
+        operation: "send",
+        machineId,
+        entityId,
+        event,
+        currentState,
+        validEvents: stateConfig && stateConfig.on ? Object.keys(stateConfig.on) : [],
+        suggestion: "Use getValidEvents() to check which events are valid for the current state"
+      });
     }
     const targetState = stateConfig.on[event];
     if (stateConfig.guards && stateConfig.guards[event]) {
@@ -17616,7 +18623,16 @@ class StateMachinePlugin extends Plugin {
           () => guard(context, event, { database: this.database, machineId, entityId })
         );
         if (!guardOk || !guardResult) {
-          throw new Error(`Transition blocked by guard '${guardName}': ${guardErr?.message || "Guard returned false"}`);
+          throw new StateMachineError(`Transition blocked by guard '${guardName}'`, {
+            operation: "send",
+            machineId,
+            entityId,
+            event,
+            currentState,
+            guardName,
+            guardError: guardErr?.message || "Guard returned false",
+            suggestion: "Check guard conditions or modify the context to satisfy guard requirements"
+          });
         }
       }
     }
@@ -17726,7 +18742,12 @@ class StateMachinePlugin extends Plugin {
   async getState(machineId, entityId) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: "getState",
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: "Check machine ID or use getMachines() to list available machines"
+      });
     }
     if (machine.currentStates.has(entityId)) {
       return machine.currentStates.get(entityId);
@@ -17752,7 +18773,12 @@ class StateMachinePlugin extends Plugin {
   async getValidEvents(machineId, stateOrEntityId) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: "getValidEvents",
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: "Check machine ID or use getMachines() to list available machines"
+      });
     }
     let state;
     if (machine.config.states[stateOrEntityId]) {
@@ -17801,7 +18827,12 @@ class StateMachinePlugin extends Plugin {
   async initializeEntity(machineId, entityId, context = {}) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: "initializeEntity",
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: "Check machine ID or use getMachines() to list available machines"
+      });
     }
     const initialState = machine.config.initialState;
     machine.currentStates.set(entityId, initialState);
@@ -17820,7 +18851,14 @@ class StateMachinePlugin extends Plugin {
         })
       );
       if (!ok && err && !err.message?.includes("already exists")) {
-        throw new Error(`Failed to initialize entity state: ${err.message}`);
+        throw new StateMachineError("Failed to initialize entity state", {
+          operation: "initializeEntity",
+          machineId,
+          entityId,
+          initialState,
+          original: err,
+          suggestion: "Check state resource configuration and database permissions"
+        });
       }
     }
     const initialStateConfig = machine.config.states[initialState];
@@ -17849,7 +18887,12 @@ class StateMachinePlugin extends Plugin {
   visualize(machineId) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: "visualize",
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: "Check machine ID or use getMachines() to list available machines"
+      });
     }
     let dot = `digraph ${machineId} {
 `;
@@ -17899,6 +18942,7 @@ exports.AuditPlugin = AuditPlugin;
 exports.AuthenticationError = AuthenticationError;
 exports.BackupPlugin = BackupPlugin;
 exports.BaseError = BaseError;
+exports.BehaviorError = BehaviorError;
 exports.CachePlugin = CachePlugin;
 exports.Client = Client;
 exports.ConnectionString = ConnectionString;
@@ -17913,15 +18957,19 @@ exports.ErrorMap = ErrorMap;
 exports.EventualConsistencyPlugin = EventualConsistencyPlugin;
 exports.FullTextPlugin = FullTextPlugin;
 exports.InvalidResourceItem = InvalidResourceItem;
+exports.MetadataLimitError = MetadataLimitError;
 exports.MetricsPlugin = MetricsPlugin;
 exports.MissingMetadata = MissingMetadata;
 exports.NoSuchBucket = NoSuchBucket;
 exports.NoSuchKey = NoSuchKey;
 exports.NotFound = NotFound;
+exports.PartitionDriverError = PartitionDriverError;
 exports.PartitionError = PartitionError;
 exports.PermissionError = PermissionError;
 exports.Plugin = Plugin;
+exports.PluginError = PluginError;
 exports.PluginObject = PluginObject;
+exports.PluginStorageError = PluginStorageError;
 exports.QueueConsumerPlugin = QueueConsumerPlugin;
 exports.ReplicatorPlugin = ReplicatorPlugin;
 exports.Resource = Resource;
@@ -17938,6 +18986,7 @@ exports.SchedulerPlugin = SchedulerPlugin;
 exports.Schema = Schema;
 exports.SchemaError = SchemaError;
 exports.StateMachinePlugin = StateMachinePlugin;
+exports.StreamError = StreamError;
 exports.UnknownError = UnknownError;
 exports.ValidationError = ValidationError;
 exports.Validator = Validator;