flowable/flowable-engine · error · FlowableIllegalArgumentException

appDefinitionId is null

Error message

appDefinitionId is null

What it means

AddIdentityLinkCmd.validateParams() requires a non-null appDefinitionId when adding an identity link to an app definition. A null id means there is no target definition, so the command fails fast with FlowableIllegalArgumentException before touching the database.

Source

Thrown at modules/flowable-app-engine/src/main/java/org/flowable/app/engine/impl/cmd/AddIdentityLinkCmd.java:48

    protected String identityId;

    protected int identityIdType;

    protected String identityType;

    public AddIdentityLinkCmd(String appDefinitionId, String identityId, int identityIdType, String identityType) {
        super(appDefinitionId);
        validateParams(appDefinitionId, identityId, identityIdType, identityType);
        this.appDefinitionId = appDefinitionId;
        this.identityId = identityId;
        this.identityIdType = identityIdType;
        this.identityType = identityType;
    }

    protected void validateParams(String appDefinitionId, String identityId, int identityIdType, String identityType) {
        if (appDefinitionId == null) {
            throw new FlowableIllegalArgumentException("appDefinitionId is null");
        }

        if (identityType == null) {
            throw new FlowableIllegalArgumentException("type is required when adding a new task identity link");
        }

        if (identityId == null) {
            throw new FlowableIllegalArgumentException("identityId is null");
        }

        if (identityIdType != IDENTITY_USER && identityIdType != IDENTITY_GROUP) {
            throw new FlowableIllegalArgumentException("identityIdType allowed values are 1 and 2");
        }
    }

    @Override
    protected Void execute(CommandContext commandContext, AppDefinition appDefinition) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Obtain a valid appDefinitionId (e.g. from the AppDefinition or deployment) before adding the identity link.
2. Add a null/empty check on the id in your calling code and fail with a clear business error.
3. If the id comes from a request parameter, validate it at the API boundary.

Example fix

// before
identityService.addIdentityLink(appDefinitionId, userId, IdentityLinkType.PARTICIPANT);
// after
if (appDefinitionId == null) {
    throw new IllegalArgumentException("appDefinitionId must be provided");
}
identityService.addIdentityLink(appDefinitionId, userId, IdentityLinkType.PARTICIPANT);

if (appDefinitionId == null || appDefinitionId.isBlank()) {
    throw new IllegalArgumentException("appDefinitionId is required");
}

try { identityService.addIdentityLink(appDefinitionId, userId, type); }
catch (FlowableIllegalArgumentException e) { log.error("Identity link rejected: " + e.getMessage()); }

When it happens

Trigger: Executing AddIdentityLinkCmd (via AppIdentityService/TaskService-style identity link APIs) with appDefinitionId == null, e.g. passing an unset variable or the result of a failed lookup straight into addIdentityLink.

Common situations: Calling runtimeService/appService identity-link APIs with a variable that was never populated; missing null checks in controller/service code before delegating to Flowable.

Related errors

• type is required when adding a new task identity link
• identityId is null
• type is required when deleting a process identity link
• userId and groupId cannot both be null
• type is required when adding a new process instance identity

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/e3ac1eb55a1da5f2. Report an issue: GitHub.