thingsboard/thingsboard · error · IllegalArgumentException

More than one related entity is not supported for relation d

Error message

More than one related entity is not supported for relation direction 'TO'. Found: {}.

What it means

RelatedEntitiesAggregationCalculatedFieldState.checkConstraintByDirection throws when a related-entities aggregation calculated field is configured with relation direction TO and the argument's entity inputs contain more than one entity. Direction TO (pointing at the current entity) is only defined for exactly one source entity, so >1 is ambiguous.

Source

Thrown at application/src/main/java/org/thingsboard/server/service/cf/ctx/state/aggregation/RelatedEntitiesAggregationCalculatedFieldState.java:323

            if (argumentEntry == null || argumentEntry.isEmpty()) {
                return ReadinessStatus.notReady(MISSING_AGGREGATION_ENTITIES_ERROR);
            }
            if (argumentEntry instanceof RelatedEntitiesArgumentEntry relatedEntitiesArgumentEntry) {
                try {
                    checkConstraintByDirection(relatedEntitiesArgumentEntry);
                } catch (Exception e) {
                    return ReadinessStatus.notReady(e.getMessage());
                }
            }
        }
        return ReadinessStatus.READY;
    }

    public void checkConstraintByDirection(RelatedEntitiesArgumentEntry relatedEntitiesArgumentEntry) {
        if (ctx.getCalculatedField().getConfiguration() instanceof RelatedEntitiesAggregationCalculatedFieldConfiguration config) {
            if (EntitySearchDirection.TO == config.getRelation().direction()) {
                if (relatedEntitiesArgumentEntry.getEntityInputs().size() > 1) {
                    throw new IllegalArgumentException("More than one related entity is not supported for relation direction 'TO'. Found: " + relatedEntitiesArgumentEntry.getEntityInputs().size() + ".");
                }
            }
        }
    }

}

View on GitHub (pinned to 45c30e83fa)

Solutions

1. Switch the relation direction to FROM if the calculation should fan out over many related entities.
2. If TO is correct, ensure exactly one inbound relation of that type exists — delete or tighten duplicates/extra relations.
3. Use a more specific relation type so only one entity matches.
4. Add a guard in onboarding so only a single TO-relation per entity/type is created.

Example fix

// config before
"relation": { "type": "Manages", "direction": "TO" }

// config after (fan-out over related devices)
"relation": { "type": "Manages", "direction": "FROM" }

// Pre-check: TO direction allows exactly one entity input
if (EntitySearchDirection.TO == config.getRelation().direction()
        && candidateEntities.size() > 1) {
    throw new IllegalStateException("Direction TO resolves " + candidateEntities.size()
        + " entities; only one is allowed — use FROM or narrow the relation type");
}

try { state.checkConstraintByDirection(entry); }
catch (IllegalArgumentException e) {
    if (e.getMessage().contains("not supported for relation direction 'TO'")) {
        // prompt: change direction to FROM or reduce matching relations to one
    } else throw e;
}

When it happens

Trigger: Related-entities aggregation field with relation.direction = TO where the relation query resolves multiple entities feeding one argument — e.g. several devices all having 'Manages' relations TO the same asset being calculated.

Common situations: Relation graph has multiple inbound relations of the chosen type; direction was left as TO when FROM was intended; test data created duplicate relations.

Related errors

• Exceeded the maximum allowed related entities per argument '
• State size exceeds the maximum allowed limit. The state will
• Argument '{}' is not a number.
• Failed to initialize CF context. The script expression is in
• Failed to initialize CF context. The expression has invalid

AI-assisted analysis of thingsboard/thingsboard@45c30e83fa (2026-08-14). Data as JSON: /api/errors/a09e208f8edb6f55. Report an issue: GitHub.