Add Classed error conditions for programmatic error handling

R/groupingsets.R

@@ -4,7 +4,7 @@ rollup = function(x, ...) {
 rollup.data.table = function(x, j, by, .SDcols, id = FALSE, label = NULL, ...) {
   # input data type basic validation
   if (!is.data.table(x))
-    stopf("Argument 'x' must be a data.table object")
+    stopf("Argument 'x' must be a data.table object", class="dt_invalid_input_error")
   if (!is.character(by))
     stopf("Argument 'by' must be a character vector of column names used in grouping.")
   if (!is.logical(id))
@@ -22,7 +22,7 @@ cube = function(x, ...) {
 cube.data.table = function(x, j, by, .SDcols, id = FALSE, label = NULL, ...) {
   # input data type basic validation
   if (!is.data.table(x))
-    stopf("Argument 'x' must be a data.table object")
+    stopf("Argument 'x' must be a data.table object", class="dt_invalid_input_error")
   if (!is.character(by))
     stopf("Argument 'by' must be a character vector of column names used in grouping.")
   if (!is.logical(id))

R/merge.R

@@ -34,7 +34,7 @@ merge.data.table = function(x, y, by = NULL, by.x = NULL, by.y = NULL, all = FAL
     warningf("Supplied both `by` and `by.x`/`by.y`. `by` argument will be ignored.")
   if (!is.null(by.x)) {
     if (length(by.x) == 0L || !is.character(by.x) || !is.character(by.y))
-      stopf("A non-empty vector of column names is required for `by.x` and `by.y`.")
+      stopf("A non-empty vector of column names is required for `by.x` and `by.y`.", class="dt_invalid_input_error")
     if (!all(idx <- by.x %chin% nm_x)) {
       stopf("The following columns listed in `%s` are missing from %s: %s", "by.x", "x", brackify(by.x[!idx]))
     }

R/setkey.R

@@ -43,7 +43,7 @@ setkeyv = function(x, cols, verbose=getOption("datatable.verbose"), physical=TRU
   if (!all(nzchar(cols))) stopf("cols contains some blanks.")
   cols = gsub("`", "", cols, fixed = TRUE)
   miss = !(cols %chin% colnames(x))
-  if (any(miss)) stopf("some columns are not in the data.table: %s", brackify(cols[miss]))
+  if (any(miss)) stopf("some columns are not in the data.table: %s", brackify(cols[miss]), class = "dt_missing_column_error")
 
   if (physical && identical(head(key(x), length(cols)), cols)){ ## for !physical we need to compute groups as well #4387
     ## key is present but x has a longer key. No sorting needed, only attribute is changed to shorter key.
@@ -54,7 +54,7 @@ setkeyv = function(x, cols, verbose=getOption("datatable.verbose"), physical=TRU
   if (".xi" %chin% names(x)) stopf("x contains a column called '.xi'. Conflicts with internal use by data.table.")
   for (i in cols) {
     .xi = x[[i]]  # [[ is copy on write, otherwise checking type would be copying each column
-    if (!typeof(.xi) %chin% ORDERING_TYPES) stopf("Column '%s' is type '%s' which is not supported as a key column type, currently.", i, typeof(.xi))
+    if (!typeof(.xi) %chin% ORDERING_TYPES) stopf("Column '%s' is type '%s' which is not supported as a key column type, currently.", i, typeof(.xi), class="dt_unsortable_type_error")
   }
   if (!is.character(cols) || length(cols)<1L) internal_error("'cols' should be character at this point") # nocov
 
@@ -266,11 +266,11 @@ setorderv = function(x, cols = colnames(x), order=1L, na.last=FALSE)
   # remove backticks from cols
   cols = gsub("`", "", cols, fixed = TRUE)
   miss = !(cols %chin% colnames(x))
-  if (any(miss)) stopf("some columns are not in the data.table: %s", brackify(cols[miss]))
+  if (any(miss)) stopf("some columns are not in the data.table: %s", brackify(cols[miss]), class = "dt_missing_column_error")
   if (".xi" %chin% colnames(x)) stopf("x contains a column called '.xi'. Conflicts with internal use by data.table.")
   for (i in cols) {
     .xi = x[[i]]  # [[ is copy on write, otherwise checking type would be copying each column
-    if (!typeof(.xi) %chin% ORDERING_TYPES) stopf("Column '%s' is type '%s' which is not supported for ordering currently.", i, typeof(.xi))
+    if (!typeof(.xi) %chin% ORDERING_TYPES) stopf("Column '%s' is type '%s' which is not supported for ordering currently.", i, typeof(.xi), class="dt_unsortable_type_error")
   }
   if (!is.character(cols) || length(cols)<1L) internal_error("'cols' should be character at this point") # nocov
 

R/setops.R

@@ -14,11 +14,11 @@ setdiff_ = function(x, y, by.x=seq_along(x), by.y=seq_along(y), use.names=FALSE)
     icnam = names(y)[lc]
     xcnam = names(x)[rc]
     if ( is.character(x[[rc]]) && !(is.character(y[[lc]]) || is.factor(y[[lc]])) ) {
-      stopf("When x's column ('%s') is character, the corresponding column in y ('%s') should be factor or character, but found incompatible type '%s'.", xcnam, icnam, typeof(y[[lc]]))
+      stopf("When x's column ('%s') is character, the corresponding column in y ('%s') should be factor or character, but found incompatible type '%s'.", xcnam, icnam, typeof(y[[lc]]), class="dt_join_type_mismatch_error")
     } else if ( is.factor(x[[rc]]) && !(is.character(y[[lc]]) || is.factor(y[[lc]])) ) {
-      stopf("When x's column ('%s') is factor, the corresponding column in y ('%s') should be character or factor, but found incompatible type '%s'.", xcnam, icnam, typeof(y[[lc]]))
+      stopf("When x's column ('%s') is factor, the corresponding column in y ('%s') should be character or factor, but found incompatible type '%s'.", xcnam, icnam, typeof(y[[lc]]), class="dt_join_type_mismatch_error")
     } else if ( (is.integer(x[[rc]]) || is.double(x[[rc]])) && (is.logical(y[[lc]]) || is.character(y[[lc]])) ) {
-      stopf("When x's column ('%s') is integer or numeric, the corresponding column in y ('%s') can not be character or logical types, but found incompatible type '%s'.", xcnam, icnam, typeof(y[[lc]]))
+      stopf("When x's column ('%s') is integer or numeric, the corresponding column in y ('%s') can not be character or logical types, but found incompatible type '%s'.", xcnam, icnam, typeof(y[[lc]]), class="dt_join_type_mismatch_error")
     }
   }
   ux = unique(shallow(x, by.x))

vignettes/datatable-programming.Rmd

@@ -456,6 +456,50 @@ DT[, eval(cl)]
 DT[, cl, env = list(cl = cl)]
 ```
 
+## Error handling with classed conditions
+
+`data.table` provides specific condition classes for common operations, making it easier to handle errors programmatically. This is particularly useful when writing robust code or packages that use `data.table`. Relying on the exact text of error messages is fragile (it is not uncommon to change the wording slightly, or for the user's session not to be in English); prefer using the signal class where possible. Please also request new signal classes if they would benefit your use case.
+
+### Available error classes
+
+`data.table` now provides four specific error classes:
+
+- `dt_missing_column_error`: When referencing columns that don't exist
+- `dt_invalid_input_error`: When providing invalid input types or empty required arguments  
+- `dt_unsortable_type_error`: When trying to sort/key unsupported types
+- `dt_join_type_mismatch_error`: When column types are incompatible in joins/set operations
+
+### Usage examples
+
+```{r error_handling, error=TRUE}
+DT <- data.table(a = 1:3, b = 4:6)
+
+# Handle missing column errors specifically
+tryCatch({
+  setkey(DT, "nonexistent_col")
+}, dt_missing_column_error = function(e) {
+  cat("Missing column detected:", conditionMessage(e), "\n")
+}, error = function(e) {
+  cat("Other error:", conditionMessage(e), "\n")
+})
+
+# Handle type mismatches in operations  
+DT1 <- data.table(id = 1:3, value = c("a", "b", "c"))
+DT2 <- data.table(id = 1:3, value = 1:3)
+
+tryCatch({
+  fintersect(DT1, DT2)
+}, dt_join_type_mismatch_error = function(e) {
+  cat("Type mismatch in join:", conditionMessage(e), "\n")
+}, error = function(e) {
+  cat("Other error:", conditionMessage(e), "\n")
+})
+```
+
+### Backward compatibility
+
+All error classes inherit from base R's condition system, so existing `tryCatch(..., error = ...)` code continues to work unchanged. The new classes simply provide more specific handling options when needed.
+
 ```{r cleanup, echo=FALSE}
 options(.opts)
 registerS3method("print", "data.frame", base::print.data.frame)