mongodb/laravel-mongodb · error · LogicException

Constant ::SCHEMA_VERSION is required when using…

Error message

Constant %s::SCHEMA_VERSION is required when using HasSchemaVersion

What it means

The HasSchemaVersion trait requires the consuming model class to define a SCHEMA_VERSION class constant, used to stamp documents with a schema version. getModelSchemaVersion() catches the Error from accessing an undefined constant and rethrows a clearer LogicException naming the class.

Solutions

Declare `public const SCHEMA_VERSION = 1;` (or the appropriate int) on the model class
Remove the HasSchemaVersion trait if schema versioning is not needed
Check that the constant is defined on the class using the trait, not a parent only when required

Example fix

// before
class Invoice extends Document { use HasSchemaVersion; }
// after
class Invoice extends Document {
    use HasSchemaVersion;
    public const SCHEMA_VERSION = 1;
}

Defensive patterns

Strategy: validation

Validate before calling

if (in_array(HasSchemaVersion::class, class_uses_recursive($modelClass), true) && !defined($modelClass . '::SCHEMA_VERSION')) {
    throw new RuntimeException($modelClass . ' must define SCHEMA_VERSION');
}

Type guard

function definesSchemaVersion(string $modelClass): bool {
    return defined($modelClass . '::SCHEMA_VERSION')
        && in_array(\MongoDB\Laravel\Eloquent\HasSchemaVersion::class, class_uses_recursive($modelClass), true);
}

Try / catch

try {
    $model = new Invoice();
} catch (LogicException $e) {
    if (str_contains($e->getMessage(), 'SCHEMA_VERSION is required')) {
        Log::error('Model using HasSchemaVersion is missing the SCHEMA_VERSION constant');
    } else {
        throw $e;
    }
}

Prevention

Define SCHEMA_VERSION immediately whenever adding the trait
Add a unit test asserting each HasSchemaVersion model defines the constant
Grep codebase for 'use HasSchemaVersion' during reviews to verify constants exist

When it happens

Trigger: Using the HasSchemaVersion trait on a model class that does not declare `public const SCHEMA_VERSION = <int>;`.

Common situations: Adding the trait via refactor and forgetting the constant; copying the trait to a new model; renaming/refactoring that removed the constant while the trait remained.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of mongodb/laravel-mongodb@0634653039 (2026-09-15). Data as JSON: /api/errors/34b2e53b51054000. Report an issue: GitHub.

Appendix: source

Thrown at src/Eloquent/HasSchemaVersion.php:79

    /**
     * Get Current document version, fallback to 0 if not set
     */
    public function getSchemaVersion(): int
    {
        return $this->{static::getSchemaVersionKey()} ?? 0;
    }

    protected static function getSchemaVersionKey(): string
    {
        return 'schema_version';
    }

    protected function getModelSchemaVersion(): int
    {
        try {
            return $this::SCHEMA_VERSION;
        } catch (Error) {
            throw new LogicException(sprintf('Constant %s::SCHEMA_VERSION is required when using HasSchemaVersion', $this::class));
        }
    }
}

View on GitHub (pinned to 0634653039)