flowable/flowable-engine · error · ActivitiException

unknown variable type name

Error message

unknown variable type name ${typeName}

What it means

CallableStatement variant of getResult: reads the variable TYPE_ name from a stored-procedure result column and resolves it against registered VariableTypes. A null resolution (including when the type name itself is null, unlike the ResultSet variant) throws this ActivitiException. It means the stored variable type cannot be mapped to any handler.

Solutions

1. Register the missing VariableType in the engine configuration so lookups succeed
2. Check the TYPE_ values returned by the stored procedure and correct/migrate them to known types
3. Verify the stored procedure returns data written by a compatible engine version

Example fix

// before
// custom type 'encrypted-string' rows unreadable
// after
configuration.setCustomPostVariableTypes(new EncryptedStringType()); // registers 'encrypted-string'

// Validate before invoking stored procedures:
String typeName = callableStmt.getString(colIndex);
if (typeName == null || engineConfig.getVariableTypes().getVariableType(typeName) == null) {
  throw new IllegalStateException("Stored procedure returned unknown variable type: " + typeName);
}

boolean isKnownVariableType(ProcessEngineConfiguration cfg, String typeName) {
  return typeName != null && cfg.getVariableTypes().getVariableType(typeName) != null;
}

try {
  result = executeProcedureAndGetVariables();
} catch (ActivitiException e) {
  if (e.getMessage().startsWith("unknown variable type name")) {
    logger.error("Procedure returned variable with unregistered TYPE_", e);
  }
  throw e;
}

When it happens

Trigger: Fetching variables through callable statements / stored-procedure result sets when the returned TYPE_ name (or null) does not match any registered VariableType.

Common situations: Legacy stored procedures returning variable rows with obsolete type names, missing custom type registration, or rows produced by an incompatible engine version.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• unknown variable type name
• Entity does not exist
• The length of the value exceeds the maximum allowed length…
• Activiti database problem
• Cannot access id method/field for JPA Entity

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/db/IbatisVariableTypeHandler.java:50

    protected VariableTypes variableTypes;

    @Override
    public VariableType getResult(ResultSet rs, String columnName) throws SQLException {
        String typeName = rs.getString(columnName);
        VariableType type = getVariableTypes().getVariableType(typeName);
        if (type == null && typeName != null) {
            throw new ActivitiException("unknown variable type name " + typeName);
        }
        return type;
    }

    @Override
    public VariableType getResult(CallableStatement cs, int columnIndex) throws SQLException {
        String typeName = cs.getString(columnIndex);
        VariableType type = getVariableTypes().getVariableType(typeName);
        if (type == null) {
            throw new ActivitiException("unknown variable type name " + typeName);
        }
        return type;
    }

    @Override
    public void setParameter(PreparedStatement ps, int i, VariableType parameter, JdbcType jdbcType) throws SQLException {
        String typeName = parameter.getTypeName();
        ps.setString(i, typeName);
    }

    protected VariableTypes getVariableTypes() {
        if (variableTypes == null) {
            variableTypes = Context
                    .getProcessEngineConfiguration()
                    .getVariableTypes();
        }
        return variableTypes;
    }

View on GitHub (pinned to d6d39ce1c6)