Database Storage Troubleshooting

This topic helps you diagnose and resolve common issues encountered when using App Builder Database Storage. It covers required setup prerequisites, authentication changes introduced with IMS token-based access, and step-by-step solutions for the most frequently reported errors. Work through each section that applies to your situation, starting with the required setup checklist before investigating specific error messages.

Required setup and versions

Before troubleshooting specific errors, confirm the following.

App Builder Data Services API is added to your workspace

In Adobe Developer Console:

  1. Open your project.
  2. Select the workspace you are using.
  3. Click Add API.
  4. Add App Builder Data Services.

This step is required for App Builder Database access and for IMS credentials to be generated.

IMS credentials are present in your .env file

After adding the API, sync credentials into your local configuration:

aio app use --merge

The command populates entries like this:

IMS_OAUTH_S2S_CLIENT_ID=...
IMS_OAUTH_S2S_CLIENT_SECRET=...
IMS_OAUTH_S2S_ORG_ID=...
IMS_OAUTH_S2S_SCOPES=["openid","AdobeID","read_organizations","adobeio.abdata.read","adobeio.abdata.write","adobeio.abdata.manage","additional_info.roles", ...]

If these values are missing, the IMS token generation for DB will not work correctly.

AIO CLI is up to date (for DB support and plugin fixes)

To use App Builder Database reliably, you must be running the following packages:

@adobe/aio-cli 11.0.2+
@adobe/aio-cli-plugin-app 14.7.0+
@adobe/aio-cli-plugin-app-storage 1.5.0+

If you previously installed early access versions of these plugins, clean them up first:

# Remove any locally installed early-access plugin versions
aio plugins:uninstall @adobe/aio-cli-plugin-app
aio plugins:uninstall @adobe/aio-cli-plugin-app-storage

# Install or update the AIO CLI globally (brings in GA plugins)
npm install -g @adobe/aio-cli

Then verify:

aio -v
aio plugins

Confirm that the versions listed meet or exceed the minimums above.

For general CLI installation and upgrade guidance, refer to the Adobe I/O Extensible CLI documentation.

Database CLI plugin is on the correct version

In your App Builder actions, ensure you are using the GA version of the DB library:

npm update @adobe/aio-lib-db

Confirm that your package.json (and the deployed code) is using:

@adobe/aio-lib-db 1.0.0 or later

Always follow the version recommendation in Getting Started with Database Storage for the most up-to-date guidance.

Migrating to IMS token authentication

App Builder Database now uses IMS token-based authentication instead of the legacy values:

If you are migrating an existing app, follow the migration steps in Getting Started with Database Storage (including adding App Builder Data Services in Developer Console, and updating your code to use generateAccessToken from @adobe/aio-sdk).

After completing the migration, use the error-specific sections below (for example, 401: OAuth token is not valid, Missing required scope, Region and provisioning errors).

// Good example action using IMS + @adobe/aio-lib-db
const { Core } = require('@adobe/aio-sdk');
const libDb = require('@adobe/aio-lib-db');

async function main(params) {
  try {
    // 1. Get IMS access token from params (requires include-ims-credentials: true)
    const tokenResponse = await Core.AuthClient.generateAccessToken(params);
    const accessToken = tokenResponse && tokenResponse.access_token;

    // 2. Initialize DB with the IMS access token
    const db = await libDb.init({ token: accessToken });

    // 3. Connect and query
    const client = await db.connect();
    const collection = await client.collection('test_collection');
    const result = await collection.find({}).toArray();

    return { statusCode: 200, body: { data: result } };
  } catch (error) {
    return { statusCode: 500, body: { error: error.message || String(error) } };
  }
}

module.exports.main = main;

Ensure app.config.yaml is similar to the following:

application:
  actions:
    my-action:
      function: actions/my-action/index.js
      annotations:
        include-ims-credentials: true

Common errors and how to fix them

The following sections describe the most common errors you may encounter when working with App Builder Database Storage, along with their likely causes and recommended fixes. Each entry includes the symptoms to look for, an explanation of what is causing the problem, and the steps needed to resolve it.

401: OAuth token is not valid

You might receive this error when:

Likely causes include:

To fix this error:

Database not provisioned (auto-provisioning issues)

You might receive this error when:

Likely causes include:

To fix this error:

Region and provisioning errors

Typical errors include:

To resolve these issues, keep the following in mind:

Make sure the region in app.config.yaml matches one of the supported regions for the Dev Console (Production vs Staging) where your project/workspace lives. If you configure an unsupported region for that Dev Console, provisioning will fail with errors such as:

No provisioning cluster configuration found for region: ...

To fix these errors:

Missing required scope: adobeio.abdata.write

You might encounter this error when running aio app db status or similar CLI commands fails with:

Failed to check database status: ... code 403: Missing required scope: adobeio.abdata.write

Likely causes include:

To fix this error:

CLI works, app times out (aio app dev / local dev)

This error occur might occur when:

Likely causes include:

To fix these errors:

Database created previously (pre-IMS) is no longer accessible

These errors might occur when:

Likely causes include:

How to check:

Confirm that you are using the same Adobe Developer Console instance (Production vs Staging) where the database was originally provisioned.

In the Developer Console, verify the runtime namespace for the workspace where the original database was created, and ensure your current app is using that exact namespace.

Confirm that the region and app.config.yaml settings match the original provisioning (if you know which region was used).

If the Dev Console instance, runtime namespace, and region all match and you still cannot see your data, contact Adobe Support or your Adobe representative with:

Action file size too large

These errors might occur when:

App Builder Runtime enforces a per-action code size limit. The documented limit is approximately 22 MB per action. Large dependencies or bundled assets can easily exceed this limit.

To stay within the per-action size limit:

Refer to System settings and limitations for the latest runtime limits and behaviors.

Error fix summary

Symptom / Error
Likely Cause
Fix (Short)
401: OAuth token is not valid from @adobe/aio-lib-db
Missing annotation, wrong token, outdated lib, env mismatch
Add include-ims-credentials: true, run aio app use --merge, pass token.access_token, update lib.
Database not provisioned despite auto-provision: true
Auto-provision bug or outdated plugin
Update CLI and plugins, run aio app db provision.
TypeError: opts.getPluginsList is not a function when using DB plugin
Old AIO CLI version
Update CLI: npm install -g @adobe/aio-cli.
No provisioning cluster configuration found for region: us-east-1
Region or environment configuration issue (often Stage)
Use a supported region (for example, amer) and re-provision.
Missing required scope: adobeio.abdata.write
App Builder Data Services API missing or not synced
Add API in console, run aio app use --merge, check IMS_OAUTH_S2S_SCOPES.
CLI works but app (aio app dev) times out
Local dev endpoint not set for region
Set AIO_DB_ENDPOINT in .env (for example, https://...-amer.app-builder.adp.adobe.io).
Old pre-IMS DB appears missing after migration
Namespace or environment mismatch
Ensure runtime namespace and environment match original; if still failing, contact support.
Action ZIP around 50 MB fails or misbehaves
Exceeds per-action size limit
Reduce bundle size, split actions, remove unused dependencies.

If you still see an error that is not covered here, capture the exact error message, region, runtime namespace, and CLI + library versions, then contact Adobe Support with those details.