Forge storage api actual value limit

Forge Forge Platform and Tools
,
1

Hey folks,

Does anyone know the actual storage limit for a single item (key/value) in Forge’s KVS? I recall hearing it might be around 32 KB, but I haven’t found any official documentation confirming that.

Even this page doesn’t mention it:

:backhand_index_pointing_right: https://developer.atlassian.com/platform/forge/runtime-reference/storage-api/

I’ve run a few tests with payloads around 250 KB, 270 KB, and 280 KB — and it’s a bit inconsistent. Sometimes they go through, but other times I hit a “Maximum item size reached” error.

Is there a definitive hard limit documented anywhere?

Here is the example I used, and sometimes works, sometimes fails (how is this even possible)?

  try {
    const bigString = 'x'.repeat(276480); // Exactly 270 KB
    console.log('Starting storage 270KB');
    await kvs.set('test-key', bigString);
    console.log('Stored successfully');
  } catch (e) {
    console.error('Error storing value:', e);
  }
2

Hello @IonScorobogaci

If you search this forum for “Forge API storage limit” you find all the prior threads on the topic as well as a link to the most recent changelog entry from 2023 that states the storage API limits.

3

Hey, thanks for direction :slight_smile:
Highlighted there is that the limit is 240 KB raw size, however a simple test I did with 245 KB, the value was stored :smiley: (have no idea what is wrong with this guys, isn’t there an exact value or what ) ?

Example I’ve used :down_arrow:

  try {
    // Generate a JSON object whose JSON.stringify size is as close as possible to 245 KB (250,880 bytes)
    const targetBytes = 245 * 1024;
    let payload = { data: '' };
    // Calculate base overhead
    const baseSize = Buffer.byteLength(JSON.stringify(payload), 'utf8');
    const fillSize = targetBytes - baseSize;
    payload.data = 'x'.repeat(fillSize);
    const serialized = JSON.stringify(payload);
    const byteLength = Buffer.byteLength(serialized, 'utf8');
    const kb = (byteLength / 1024).toFixed(2);
    console.log(`Generated JSON of size: ${kb} KB (${byteLength} bytes)`);
    await kvs.set('test-key', serialized);
    console.log('Stored successfully');
  } catch (e) {
    console.error('Error storing value:', e);
  }
4

Hi Ion, the limit on KVS value size is 240KB. All KVS limits are listed here https://developer.atlassian.com/platform/forge/platform-quotas-and-limits/#key-and-object-size-limits

1 Like
5

Hey Anatoly, thanks a lot for input, appreciate it :slight_smile:
But how about this example, where i’m able to store 255KiB :thinking: ?
Is there a hard limit or it’s just a soft limit used for documentation only :blush:

Example storing with success a value of 255KiB (raw)

  try {
    const targetBytes = 255 * 1024;
    let payload = { data: '' };
    const baseSize = Buffer.byteLength(JSON.stringify(payload), 'utf8');
    const fillSize = targetBytes - baseSize;
    payload.data = 'x'.repeat(fillSize);
    const serialized = JSON.stringify(payload);
    const byteLength = Buffer.byteLength(serialized, 'utf8');
    const kb = (byteLength / 1024).toFixed(2);
    console.log(`Generated JSON of size: ${kb} KB (${byteLength} bytes)`);
    await kvs.set('test-key', serialized);
    console.log('Stored successfully');
  } catch (e) {
    console.error('Error storing value:', e);
  }
6

Ion,

KVS value size limit uses approximation for performance reasons. We’ll double-check why it was possible to exceed the limit in this specific case.

That said, we strongly recommend not exceeding the documented 240KB limit. Even if larger values may appear to work in some cases today, we can’t guarantee this behavior will remain consistent or supported in the future.

2 Likes