OtterMind/Chat2DB · error · BusinessException

largeCellValue.rowLocatorRequired

largeCellValue.rowLocatorRequired

Error message

largeCellValue.rowLocatorRequired

What it means

Thrown by prepareStatement() when the LargeValueReference has a null or empty primary key. The large-value lookup builds 'SELECT col FROM table WHERE pk = ?' and cannot locate a row without primary-key coordinates.

Source

Thrown at chat2db-community-server/chat2db-community-domain/chat2db-community-domain-core/src/main/java/ai/chat2db/community/domain/core/impl/db/DbCellValueServiceImpl.java:124

            throw new BusinessException("largeCellValue.downloadFailed", new Object[]{e.getMessage()}, e);
        }
    }

    private int normalizeLimit(Integer limit, CellValueFormatEnum format) {
        int resolved = limit == null || limit <= 0 ? DEFAULT_CHUNK_SIZE : limit;
        resolved = Math.min(resolved, MAX_CHUNK_SIZE);
        if (format.isBase64() && resolved < BASE64_BYTE_GROUP) {
            return BASE64_BYTE_GROUP;
        }
        if (format.isBase64() && resolved > BASE64_BYTE_GROUP) {
            return resolved - (resolved % BASE64_BYTE_GROUP);
        }
        return resolved;
    }

    private PreparedStatement prepareStatement(LargeValueReference reference) throws SQLException {
        if (reference.getPrimaryKey() == null || reference.getPrimaryKey().isEmpty()) {
            throw new BusinessException("largeCellValue.rowLocatorRequired");
        }
        Connection connection = Chat2DBContext.getConnection();
        IDbMetaData metaData = Chat2DBContext.getDbMetaData();
        QualifiedTableName tableName = parseQualifiedTableName(reference);
        StringBuilder sql = new StringBuilder();
        sql.append("SELECT ")
                .append(metaData.getMetaDataName(reference.getColumnName()))
                .append(" FROM ")
                .append(metaData.getQualifiedTableName(tableName.databaseName(), tableName.schemaName(),
                        tableName.tableName()))
                .append(" WHERE ");
        boolean first = true;
        for (String columnName : reference.getPrimaryKey().keySet()) {
            if (!first) {
                sql.append(" AND ");
            }
            sql.append(metaData.getMetaDataName(columnName)).append(" = ?");
            first = false;

View on GitHub (pinned to 5ee1e990e7)

Solutions

1. Ensure the source table has a primary key or unique identifier so a row locator can be captured.
2. For non-editable result sets without identity, inform the user that large-cell read/download is unavailable (see largeCellValue.fullValueUnsupported).
3. Validate the reference carries a non-empty primary key before calling readChunk/prepareDownload.

Example fix

// before
// reference with null primaryKey reaches prepareStatement()
// after (caller guard)
if (reference.getPrimaryKey() == null || reference.getPrimaryKey().isEmpty()) {
    throw new BusinessException("largeCellValue.rowLocatorRequired");
}

// Guard before readChunk/prepareDownload
List<Object> pk = reference.getPrimaryKey();
if (pk == null || pk.isEmpty()) {
    // large-cell read/download is unavailable; tell the user the row must be uniquely identifiable
    return Result.fail("largeCellValue.rowLocatorRequired");
}

// Java guard narrowing on reference identity
boolean hasRowLocator(LargeValueReference ref) {
    return ref != null && ref.getPrimaryKey() != null && !ref.getPrimaryKey().isEmpty();
}

When it happens

Trigger: readChunk() or prepareDownload() is called with a reference whose getPrimaryKey() is null/empty — typically because the source result row was not uniquely identifiable (no primary key on the table, or a custom query without a row locator).

Common situations: Querying a table or view that has no primary key / no unique index, so the reference could not capture row locator info; or the reference was built from a result set that doesn't expose editable row identity.

Related errors

• largeCellValue.rowNotFound
• largeCellValue.readFailed
• largeCellValue.downloadFailed
• largeCellValue.partialPreviewEditRejected
• largeCellValue.tokenRequired

AI-assisted analysis of OtterMind/Chat2DB@5ee1e990e7 (2026-08-14). Data as JSON: /api/errors/2711351c296186aa. Report an issue: GitHub.