pocketbase/pocketbase · error

failed to initialize relation field %q

Error message

failed to initialize relation field %q

What it means

Internal invariant: a field whose Type() is FieldTypeRelation failed the assertion to *RelationField during direct-relation joining. Should not occur with built-in field types; custom field plugins returning the relation type without embedding RelationField are the usual cause.

Source

Thrown at core/record_field_resolver_runner.go:643

			}

			r.multiMatchActiveTableAlias = newTableAlias2
			// ---

			continue
		}
		// -----------------------------------------------------------

		// check for direct relation
		if field.Type() != FieldTypeRelation {
			return nil, fmt.Errorf("field %q is not a valid relation", prop)
		}

		// join the relation to the main query
		// ---
		relField, ok := field.(*RelationField)
		if !ok {
			return nil, fmt.Errorf("failed to initialize relation field %q", prop)
		}

		relCollection, relErr := r.resolver.loadCollection(relField.CollectionId)
		if relErr != nil {
			return nil, fmt.Errorf("failed to load field %q collection", prop)
		}

		// "id" lookups optimization for single relations to avoid unnecessary joins,
		// aka. "user.id" and "user" should produce the same query identifier
		if !relField.IsMultiple() &&
			// the penultimate prop is "id"
			i == totalProps-2 && r.activeProps[i+1] == FieldNameId {
			return r.finalizeActivePropsProcessing(collection, relField.Name, i)
		}

		cleanFieldName := inflector.Columnify(relField.Name)
		prefixedFieldName := r.activeTableAlias + "." + cleanFieldName
		newTableAlias := r.activeTableAlias + "_" + cleanFieldName + r.resolver.joinAliasSuffix

View on GitHub (pinned to 5d217ddb50)

Solutions

1. Replace the custom field with a standard relation field.
2. Fix or update the plugin so relation-typed fields implement/extend core.RelationField.
3. Pin compatible versions of core and plugins.

func isStandardRelation(f core.Field) bool {
    if f.Type() != core.FieldTypeRelation {
        return false
    }
    _, ok := f.(*core.RelationField)
    return ok
}

if err != nil && strings.Contains(err.Error(), "failed to initialize relation field") {
    log.Error("field plugin/type mismatch", "field", prop)
    return errors.New("unsupported relation field implementation")
}

When it happens

Trigger: A dotted filter path traversing a custom field that claims FieldTypeRelation but is not a *RelationField implementation.

Common situations: Buggy third-party field plugins; modified PocketBase forks; version mismatches after upgrading core while keeping old plugins.

Related errors

• failed to initialize back relation field %q
• failed to initialize data relation field %q
• non-filterable field %q
• max nested relations reached for field %q
• failed to load back relation field %q collection

AI-assisted analysis of pocketbase/pocketbase@5d217ddb50 (2026-08-15). Data as JSON: /api/errors/aa9574b62c214632. Report an issue: GitHub.