Last updated Aug 29, 2025

Error handling for Forge Cache

We are in the process of ending the Forge Cache EAP. This capability will not progress to GA, as we are shifting our investments to better address developer use-cases.

As of August 29, 2025 we will not accept any new sign-ups to the Cache EAP.
On September 30, 2025, we will delete all data in Forge Cache. We will also decommission its EAP environment completely.

For more details about this update, refer to the changelog.

The @forge/cache package throws errors along with their error codes. The following example shows how to handle an error when the app tries to store a value that exceeds the maximum allowed size.

1
2
import { cache, errorCodes } from '@forge/cache'; 
try { 
  const cacheClient = cache.connect();
  await cacheClient.set("hello", 3, { ttlSeconds: 10 });
} 
catch (error) { 
  if (error.code === errorCodes.MAX_VALUE_SIZE_EXCEEDED) { 
    // Handle when value of key is above the max allowed value
  } 
}

Error code	Description
`INVALID_KEY_TYPE`	The provided key is not a string. Ensure that you are passing a string value for the key.
`MIN_VALID_KEY_LENGTH_REQUIRED`	The provided key needs to be more than one character. See the Forge Cache limits for more details.
`INVALID_KEY_PATTERN`	The provided key does not match the regular expression (regex). Ensure that the key matches the regex: `/^(?!\s+$)[a-zA-Z0-9:._\s-#]+$/`
`VALUE_IS_NOT_A_STRING`	The provided value is not a string type. Ensure the provided type of value is a string.
`VALUE_IS_REQUIRED`	The provided value could not be found. Ensure there is a provided value.
`INVALID_VALUE_TYPE`	The provided value is an invalid type type. Ensure the provided type of value is a string.
`MAX_VALUE_SIZE_EXCEEDED`	The provided value has exceeded the maximum valid size of 240 KiB. See the Forge Cache limits for more details.
`INVALID_LIMIT_VALUE`	The provided limit value is invalid. Ensure the provided value only contains digits and is between 30s and 3600s. See the Forge Cache limits for more details.

Error code	Description
`VALUE_IS_NOT_A_STRING`	The provided value is not a string type.
`VALUE_IS_REQUIRED`	Ensure there is a provided value.
`INVALID_VALUE_TYPE`	The provided value is an invalid type type. Ensure the provided type of value is a string.
`MAX_VALUE_SIZE_EXCEEDED`	The provided value has exceeded the maximum valid size of 240KiB. See the Forge Cache limits for more details.
`INVALID_LIMIT_VALUE`	The provided limit value is invalid. Ensure the provided value only contains digits and is between 30s and 3600s. See the Forge Cache limits for more details.

Error code	Description
`INVALID_TTL_TYPE`	The provided `ttlSeconds` is an invalid type. Ensure the provided type of value is an integer.
`VALUE_IS_REQUIRED`	The provided value could not be found. Ensure there is a provided value.
`INVALID_VALUE_TYPE`	The provided value is an invalid type type. Ensure the provided type of value is a string.
`MAX_VALUE_SIZE_EXCEEDED`	The provided value has exceeded the maximum valid size. Ensure the provided value is under 240 KiB. See the Forge Cache limits for more details.
`INVALID_LIMIT_VALUE`	The provided limit value is invalid. Ensure the provided value only contains digits and is between 30s and 3600s. See the Forge Cache limits for more details.