9  Error Messages & User Experience

JASP targets researchers and students who may have limited statistical or programming experience. Every analysis should guide users towards correct interpretation and fail gracefully when something goes wrong.

9.1 Design Philosophy

Three principles from the JASP Human Guide:

  1. Be proactive, not reactive — check assumptions and warn before producing misleading results.
  2. Write for humans — error messages should explain what went wrong and suggest a fix, not dump a stack trace.
  3. Be consistent — use the standardised error messages below so users learn to recognise common patterns.

9.2 Types of Messages

Type Where it appears Purpose
Analysis error Red banner above results Unrecoverable problem — analysis cannot produce output
Footnote Below a table Warning or caveat about specific results
Value error Inline in a table cell A specific cell could not be computed

9.2.1 Setting an Analysis Error

table <- createJaspTable(title = "Results")
table$setError("The dependent variable contains only missing values.")

The error is attached to a specific output element (table, plot, or container). If attached to a container, all child elements inherit the error state.

9.2.2 Adding Footnotes

table$addFootnote(
  message = gettext("Levene's test is significant (p < .05), suggesting a violation of the equal variances assumption."),
  colNames = "p",
  rowNames = "levene"
)

9.2.3 .hasErrors() — Validate Before Computing

Call .hasErrors() on your dataset to check common problems before attempting computation:

.hasErrors(dataset,
  type = c("infinity", "observations", "variance"),
  observations.amount = "< 2",
  exitAnalysisIfErrors = TRUE
)

Available check types:

Type What it checks
infinity Infinite values in the data
observations Too few observations (specify observations.amount)
variance Zero variance in a variable
factorLevels Too few factor levels (specify factorLevels.amount)
negativeValues Negative values where not expected
integerValues Non-integer values where integers are required
duplicateValues Duplicate values in a variable

When exitAnalysisIfErrors = TRUE, the error is set automatically and the analysis stops cleanly.

9.3 Standardised Error Messages

Use these exact phrasings when the situation matches. This ensures consistency across all JASP modules and simplifies translation.

9.3.1 Not Enough Observations

“Not enough observations. The analysis requires at least N observations.”

9.3.2 Not Enough Factor Levels

“The factor ‘variable’ has fewer than 2 levels after removing empty levels.”

9.3.3 Zero Variance

“The variable ‘variable’ has zero variance. The analysis cannot proceed.”

9.3.4 Infinite Values

“The variable ‘variable’ contains infinite values.”

9.3.5 Singular Matrix / Convergence Failures

“The model could not be estimated. The design matrix is (near-)singular.”

“The model did not converge within N iterations.”

9.3.6 Bayesian-Specific

“The Bayes factor could not be computed. This may be due to a singular design matrix.”

“The posterior samples could not be obtained. Consider increasing the number of MCMC samples.”

9.4 Assumption Checking

JASP analyses should check assumptions and report violations as footnotes:

if (leveneResult$p < 0.05) {
  table$addFootnote(
    message = gettext("Levene's test is significant (p < .05), suggesting a violation of the equal variances assumption.")
  )
}

9.4.1 Where to Validate

Validate at system boundaries only:

Boundary Action
Dataset columns Use .hasErrors() checks
User text input (TextField, FormulaField) Validate in QML via inputType or in R
Numeric input (IntegerField, DoubleField) Use QML min/max properties
QML dropdowns / checkboxes No validation needed — values are constrained by the UI

Do not add defensive checks for values that cannot occur because the UI prevents them. Trust QML input constraints.

9.5 Writing Good Error Messages

TipChecklist

Good: gettextf("The grouping variable '%s' has fewer than 2 levels. Ensure both groups are present in the data.", groupVar)

Bad: "Error in grouping variable" — says nothing about the cause or remedy.