flarum/framework · error · Exception

Unknown relationship type for relation

Error message

Unknown relationship type for relation: {methodName}

What it means

Flarum's PHPStan extension models Eloquent relation return types; RelationProperty::getReadableType() matches the called method name against hasMany/belongsToMany/hasOne/belongsTo (plus the two collection-returning variants) and throws a plain Exception for anything else. getWritableType() delegates to getReadableType(), so an unknown method name fails on either path. It means the extension encountered a method call it doesn't recognise as a supported relation type.

Solutions

1. Restrict analysed code to the supported relation methods (hasMany, belongsToMany, hasOne, belongsTo) or refactor morph*/hasManyThrough relations to supported ones
2. Patch the extension's match arm to handle the relation type you use (e.g. add 'hasManyThrough' => GenericObjectType with proper generics)
3. Check the actual method name being analysed for typos

Example fix

// before
public function comments(): HasManyThrough // unsupported
// after
public function comments(): HasMany // or extend the match in RelationProperty.php

$supported = ['hasMany','belongsToMany','hasOne','belongsTo'];
if (!in_array($methodName, $supported, true)) { /* fall back to mixed type or skip analysis */ }

try { $type = $relationProperty->getReadableType(); } catch (Exception $e) { $type = new MixedType(); }

When it happens

Trigger: PHPStan analysing code that invokes an unlisted relationship-style method through the analysed path — e.g. `hasManyThrough`, `morphMany`, `morphToMany`, or a custom relation method name passed into the RelationProperty analysis.

Common situations: Extending the PHPStan extension to cover Laravel relations beyond the four Flarum supports; analysing extension code that uses morph* relations; typos in relation method names.

Related errors

• Unable to resolve extender for '.$value->var::class
• Cannot delete the root admin
• $modelClass must use the HasFactory trait and have a…

AI-assisted analysis of flarum/framework@4b939f6853 (2026-09-15). Data as JSON: /api/errors/523366936fdc694b. Report an issue: GitHub.

Appendix: source

Thrown at php-packages/phpstan/src/Relations/RelationProperty.php:69

    public function isPublic(): bool
    {
        return true;
    }

    public function getDocComment(): ?string
    {
        return null;
    }

    public function getReadableType(): Type
    {
        return match ($this->methodCall->methodName) {
            'hasMany', 'belongsToMany' => new GenericObjectType(Collection::class, [
                new IntegerType(),
                new ObjectType($this->methodCall->arguments[1]->class->toString())
            ]),
            'hasOne', 'belongsTo' => new ObjectType($this->methodCall->arguments[1]->class->toString()),
            default => throw new Exception('Unknown relationship type for relation: '.$this->methodCall->methodName),
        };
    }

    public function getWritableType(): Type
    {
        return $this->getReadableType();
    }

    public function canChangeTypeAfterAssignment(): bool
    {
        return false;
    }

    public function isReadable(): bool
    {
        return true;
    }

View on GitHub (pinned to 4b939f6853)