What causes "Integration not found: ${JSON.stringify(integrationKey)}" in hcengineering/platform?

Verify the integrationKey string against the registered integrations (list them via the client or admin UI).

hcengineering/platform · error · Error

Integration not found: ${JSON.stringify(integrationKey)}

Error message

Integration not found: ${JSON.stringify(integrationKey)}

What it means

updateConfig fetches the integration identified by integrationKey before merging the new config. If getIntegration returns null/undefined, there is no integration registered under that key, so the client throws with a JSON dump of the key. This prevents silently creating orphaned config updates.

Source

Thrown at packages/integration-client/src/client.ts:205

        operation: 'connect',
        error: error instanceof Error ? error.message : String(error),
        socialId,
        timestamp: Date.now()
      }
      this.emit('integration:error', errorData)
      throw error
    }
  }

  async updateConfig (
    integrationKey: IntegrationKey,
    config: Record<string, any>,
    refresh?: () => Promise<void>
  ): Promise<void> {
    try {
      const integration = await this.client.getIntegration(integrationKey)
      if (integration == null) {
        throw new Error(`Integration not found: ${JSON.stringify(integrationKey)}`)
      }

      const oldConfig = integration.data?.config
      const data = {
        ...integration.data,
        config
      }

      await this.client.updateIntegration({
        ...integration,
        data
      })
      if (refresh != null) {
        await refresh()
      }

      const eventData: IntegrationUpdatedData = {
        integration,

View on GitHub (pinned to 63e28dc964)

Solutions

Verify the integrationKey string against the registered integrations (list them via the client or admin UI).
Check you are pointing the client at the correct workspace/environment where the integration exists.
Register or re-install the integration before calling updateConfig.
Fix casing/typo in the key — keys are exact-match strings.

Example fix

// before
await client.updateConfig('slack-integraton', config)
// after
const key = 'slack-integration'
if (await client.getIntegration(key) != null) {
  await client.updateConfig(key, config)
}

Defensive patterns

Strategy: validation

Validate before calling

const integration = await client.getIntegration(integrationKey)
if (integration == null) throw new Error(`Cannot update config: integration ${integrationKey} is not registered`)

Try / catch

try {
  await client.updateConfig(integrationKey, config)
} catch (err) {
  if (err instanceof Error && err.message.includes('Integration not found')) {
    // register the integration or correct the key
  } else {
    throw err
  }
}

Prevention

Keep integration keys in a single shared constants module, never inline strings.
Check integration existence with getIntegration before mutating it.
Distinguish per-environment keys (staging vs production) in config.

When it happens

Trigger: Calling integrationClient.updateConfig(integrationKey, config, refresh?) where the backend has no integration matching integrationKey.

Common situations: Typo in the integration key; integration removed or not yet registered on the server; using a key from a different workspace/environment (staging vs production).

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/47317a809f6a84db. Report an issue: GitHub.