OtterMind/Chat2DB · error · BusinessException

largeCellValue.tokenRequired

largeCellValue.tokenRequired

Error message

largeCellValue.tokenRequired

What it means

Thrown by DbLargeValueTokenServiceImpl.requireValid when the supplied token id is blank. Large cell values (>display threshold) are fetched by an opaque LargeValueToken id issued when the result set is rendered; a blank id means the caller never had or lost the reference. Resolves to 'Large value reference is required'. This is an input-contract check before cache lookup.

Source

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

                    continue;
                }
                Map<String, Object> primaryKey = getPrimaryKeyValues(primaryKeyHeaders, row);
                if (primaryKey.isEmpty()) {
                    cell.setUnsupportedReason(UNSUPPORTED_REASON_KEY);
                    continue;
                }
                LargeValueToken token = createToken(dataSourceId, databaseName, schemaName, tableName,
                        columnName, primaryKey, cell);
                tokenCache.put(token.getId(), token);
                cell.setLargeValueId(token.getId());
            }
        }
    }

    @Override
    public LargeValueToken requireValid(String id) {
        if (StringUtils.isBlank(id)) {
            throw new BusinessException("largeCellValue.tokenRequired");
        }
        LargeValueToken token = tokenCache.get(id);
        if (token == null) {
            throw new BusinessException("largeCellValue.tokenExpired");
        }
        if (Instant.now().isAfter(token.getExpiresAt())) {
            tokenCache.remove(id);
            throw new BusinessException("largeCellValue.tokenExpired");
        }
        validateOwner(token);
        return token;
    }

    private void cleanupExpired() {
        Instant now = Instant.now();
        tokenCache.entrySet().removeIf(entry -> now.isAfter(entry.getValue().getExpiresAt()));
    }

View on GitHub (pinned to 5ee1e990e7)

Solutions

1. Always read largeValueId from the cell metadata returned during result rendering before calling the fetch endpoint.
2. Treat a blank id as a client-side error and prompt the user to re-open the cell rather than submitting.
3. Ensure the result-set render path runs the tokenization step that populates cell.largeValueId.

if (StringUtils.isBlank(cell.getLargeValueId())) {
    // do not call the large-value endpoint; re-open the cell
}

When it happens

Trigger: The large-value detail/fetch endpoint called with a missing/empty largeValueId query param; a frontend that opened a large cell but failed to persist the issued token id before requesting the body.

Common situations: Deep link to a large cell without the token; a stale front-end state where the cell's largeValueId was cleared on re-render; an API client that constructed the URL manually and omitted the id.

Related errors

• largeCellValue.rowLocatorRequired
• largeCellValue.partialPreviewEditRejected
• request.required
• exportType
• sql

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