actualbudget/actual · error

Pluggy credentials are not configured

Error message

Pluggy credentials are not configured

What it means

getPluggyClient builds a PluggyClient from credentials stored in the secrets service. It resolves credentials either per-budget-file or globally; if neither source has clientId, clientSecret, and itemIds configured, it throws 'Pluggy credentials are not configured'. The server refuses to create a Pluggy client without credentials rather than failing later with an auth error from Pluggy.

Source

Thrown at packages/sync-server/src/app-pluggyai/pluggyai-service.js:51

    SecretName.pluggyai_clientSecret,
    credentialFileId,
  );

  return {
    cacheKey: JSON.stringify({
      fileId: credentialFileId,
      [SecretName.pluggyai_clientId]: clientId,
      [SecretName.pluggyai_clientSecret]: clientSecret,
    }),
    clientId,
    clientSecret,
  };
}

function getPluggyClient(fileId) {
  const credentialSource = getCredentialSource(fileId);
  if (!credentialSource) {
    throw new Error('Pluggy credentials are not configured');
  }

  const credentialFileId =
    credentialSource === 'per-budget-file' ? fileId : null;
  const { cacheKey, clientId, clientSecret } =
    getCredentialsCacheEntry(credentialFileId);
  let pluggyClient = pluggyClients.get(cacheKey);
  if (!pluggyClient) {
    pluggyClient = new PluggyClient({
      clientId,
      clientSecret,
    });
    pluggyClients.set(cacheKey, pluggyClient);
  }

  return pluggyClient;
}

View on GitHub (pinned to d4334cb6e6)

Solutions

1. Set the Pluggy credentials (PLUGGAI_CLIENT_ID, PLUGGAI_CLIENT_SECRET, PLUGGAI_ITEM_IDS) on the sync server environment and restart it.
2. If using per-budget secrets, open the specific budget and set the three Pluggy secrets in that budget's settings.
3. Verify isConfigured(fileId) returns true before triggering a Pluggy sync.
4. Check which credential source applies (per-budget vs global) and make sure the intended one is populated.

Example fix

// before (server env)
# no pluggy vars

// after (server env)
PLUGGAI_CLIENT_ID=your-client-id
PLUGGAI_CLIENT_SECRET=your-client-secret
PLUGGAI_ITEM_IDS=item-1,item-2

if (!pluggyaiService.isConfigured(fileId)) {
  throw new Error('Pluggy credentials missing: set PLUGGAI_CLIENT_ID, PLUGGAI_CLIENT_SECRET, PLUGGAI_ITEM_IDS');
}

When it happens

Trigger: Calling any pluggyaiService method (e.g. getAccountsByItemId, getTransactions) when secrets pluggyai_clientId, pluggyai_clientSecret, or pluggyai_itemIds are missing both globally and for the given budget fileId.

Common situations: Self-hosted sync server without PLUGGAI_CLIENT_ID/PLUGGAI_CLIENT_SECRET/PLUGGAI_ITEM_IDS env vars set; per-budget secrets configured for a different budget file than the one being synced; credentials were deleted or the server was restarted with a different environment.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• not-configured
• results.reason
• results.error
• Error loading data into the spreadsheet.
• Unsupported summary type

AI-assisted analysis of actualbudget/actual@d4334cb6e6 (2026-08-29). Data as JSON: /api/errors/fbae1bb9551df2f9. Report an issue: GitHub.