Error Codes Reference

This document describes all validation error codes used by PRISM and how to fix them.

PRISM Error Code System

All errors now use structured codes in the format PRISMxxx:

Code Range	Category	Description
PRISM0xx	Dataset Structure	Dataset-level issues
PRISM1xx	File Naming	Filename pattern errors
PRISM2xx	Sidecar/Metadata	Missing or invalid sidecars
PRISM3xx	Schema Validation	JSON schema errors
PRISM4xx	Content Validation	Data content issues
PRISM5xx	BIDS Compatibility	BIDS-specific warnings
PRISM9xx	System/Plugin	Internal or plugin errors

Dataset Structure Errors (PRISM0xx)

PRISM001 - Missing dataset_description.json

Description: The required dataset_description.json file is missing from the dataset root.

Fix Hint: Create a dataset_description.json file at the dataset root with required fields: Name, BIDSVersion

Auto-fixable: ✅ Yes (--fix creates a template)

Example Fix:

{
  "Name": "My Dataset",
  "BIDSVersion": "1.9.0",
  "DatasetType": "raw"
}

PRISM002 - No subjects found

Description: No subject directories (starting with sub-) were found in the dataset.

Fix Hint: Ensure subject folders are named sub-<label> and located at the dataset root.

Auto-fixable: ❌ No (requires data reorganization)

PRISM003 - Invalid dataset_description.json

Description: The dataset_description.json file exists but contains invalid JSON or missing required fields.

Fix Hint: Ensure the file contains valid JSON with required BIDS fields.

PRISM004 - Missing participants.tsv

Description: The participants.tsv file is missing.

Fix Hint: Create a participants.tsv file listing all subjects with at least a participant_id column.

File Naming Errors (PRISM1xx)

PRISM101 - Invalid filename pattern

Description: Filename does not follow BIDS naming conventions.

Fix Hint: Use BIDS naming: sub-<label>[_ses-<label>][_task-<label>]_<suffix>.<ext>

Examples of Valid Filenames:

sub-01_task-faces_bold.nii.gz
sub-01_ses-01_task-nback_eeg.edf
sub-02_task-rest_physio.tsv

Examples of Invalid Filenames:

subject01_task-faces.nii.gz ❌ (missing sub- prefix)
sub-01-task-faces.nii.gz ❌ (use _ not - between entities)

PRISM102 - Subject ID mismatch

Description: The subject ID in the filename doesn’t match the parent directory.

Fix Hint: Ensure the sub-<label> in the filename matches the parent directory name.

PRISM103 - Session ID mismatch

Description: The session ID in the filename doesn’t match the parent directory.

Fix Hint: Ensure the ses-<label> in the filename matches the parent directory name.

PRISM104 - Invalid characters

Description: Filename contains invalid characters.

Fix Hint: Use only alphanumeric characters, hyphens, and underscores.

Sidecar/Metadata Errors (PRISM2xx)

PRISM201 - Missing sidecar

Description: A data file is missing its required JSON sidecar.

Fix Hint: Create a JSON sidecar with the same base name as the data file.

Auto-fixable: ✅ Yes (--fix creates template sidecars)

Example:

sub-01/survey/sub-01_task-demo_survey.tsv     # Data file
sub-01/survey/sub-01_task-demo_survey.json    # Required sidecar (auto-created by --fix)

PRISM202 - Invalid JSON syntax

Description: The JSON sidecar contains syntax errors.

Fix Hint: Validate JSON syntax - check for missing quotes, trailing commas, etc.

PRISM203 - Empty sidecar

Description: The JSON sidecar is empty or contains only {}.

Fix Hint: Add required metadata fields to the sidecar.

Schema Validation Errors (PRISM3xx)

PRISM301 - Missing required field

Description: A required field is missing from the sidecar according to the loaded PRISM schema. This includes both standard BIDS requirements and PRISM-specific mandatory extensions (e.g., StimulusPresentation for events).

Fix Hint: Add the missing property to the JSON sidecar. PRISM schemas often require additional metadata (like software details or hardware settings) to ensure experimental reproducibility beyond the core BIDS standard.

Example (PRISM Extension): For _events.json files, PRISM requires the StimulusPresentation object:

{
    "StimulusPresentation": {
        "SoftwareName": "PsychoPy",
        "SoftwareVersion": "2023.2.3"
    }
}

PRISM302 - Invalid field type

Description: A field has the wrong data type (e.g., string instead of number).

Fix Hint: Correct the field type according to the schema.

PRISM303 - Invalid field value

Description: A field value is outside the allowed range or not in the enum.

Fix Hint: Use a valid value from the schema definition.

BIDS Compatibility Warnings (PRISM5xx)

PRISM501 - .bidsignore needs update

Description: The .bidsignore file needs to be updated for PRISM compatibility.

Fix Hint: Add PRISM-specific directories to .bidsignore so standard BIDS tools ignore them.

Auto-fixable: ✅ Yes

PRISM502 - BIDS validator warning

Description: The standard BIDS validator reported a warning.

Fix Hint: Review the BIDS validator output for details.

Plugin/System Errors (PRISM9xx)

PRISM900 - Plugin issue

Description: A validation issue reported by a custom plugin.

Fix Hint: Check the plugin-specific message for details.

PRISM901 - Plugin failure

Description: A plugin failed to execute.

Fix Hint: Check plugin code for errors; ensure validate() function returns a list.

PRISM999 - Internal error

Description: An unexpected internal error occurred.

Fix Hint: Report this issue on GitHub with full error details.

Legacy Error Names

For backwards compatibility, these legacy error names map to PRISM codes:

Legacy Name	PRISM Code
INVALID_BIDS_FILENAME	PRISM101
MISSING_SIDECAR	PRISM201
SCHEMA_VALIDATION_ERROR	PRISM301-303
INVALID_JSON	PRISM202
FILENAME_PATTERN_MISMATCH	PRISM101

Auto-Fix Support

Many issues can be automatically fixed using --fix:

# Preview fixes without applying
python prism-validator /path/to/dataset --dry-run

# Apply fixes
python prism-validator /path/to/dataset --fix

# List all fixable issues
python prism-validator --list-fixes

Auto-fixable issues:

PRISM001: Creates template dataset_description.json
PRISM201: Creates template JSON sidecars
PRISM501: Updates .bidsignore for PRISM compatibility

Getting Help

If you’re still stuck after reading this documentation:

Check QUICK_START.md for general guidance
Review example datasets in docs/examples/
Open an issue on GitHub
Consult the BIDS Specification