Skip to content

If an upgrade causes issues, revert to the previous working version by deploying the prior container image. Because each connector versions independently of the Context Engine, you can roll back a single connector without touching the rest of the deployment. Rolling back the Context Engine itself has an extra step, because its upgrades migrate its database (see Rolling Back the Context Engine).

Check your deployment history (for example, the image tags of earlier revisions or task definitions) for the last known good version. If you are unsure which version to return to, confirm it with Caprus AI support.

The examples below roll back the Essbase connector (agentcube-essbase). The same commands apply to agentcube-planning and agentcube-fccs.

PowerShell
az containerapp update --name {app_name} --resource-group {resource_group} --image ghcr.io/caprusai/agentcube-essbase:{previous_version} --revision-suffix "rollback-{timestamp}"
bash
az containerapp update \
--name {app_name} \
--resource-group {resource_group} \
--image ghcr.io/caprusai/agentcube-essbase:{previous_version} \
--revision-suffix "rollback-{timestamp}"

Revision suffixes allow only lowercase letters, numbers and hyphens, so use a value without dots for {timestamp} (for example 20261006-1430).

PowerShell
Invoke-RestMethod https://{connector_hostname}/health
bash
curl https://{connector_hostname}/health

Confirm version shows the previous version and status is healthy.

Run a tool call from your AI platform to verify end-to-end functionality.

Context Engine upgrades apply database migrations automatically at startup, and migrations cannot be reversed. Redeploying the previous agentcube-ce image does not undo them. A safe Context Engine rollback therefore depends on a backup taken before the upgrade (see Upgrades → Context Engine Upgrades):

  1. Restore the pre-upgrade backup (snapshot or pg_dump) of the Context Engine PostgreSQL database.
  2. Deploy the previous ghcr.io/caprusai/agentcube-ce:{previous_version} image with the same environment settings and the same AGENTCUBE_CE_CREDENTIAL_KEY, using the commands above.
  3. Verify with GET https://{ce_hostname}/health and a test tool call.

Never start an older image against a database a newer version has migrated. If you roll back to a release that predates license installation through the admin console, contact Caprus AI support before you do.

If SSO is causing issues, you can revert a connector to a non-SSO auth mode without changing the container image. A connector’s auth mode is set in two places, and both must match: the connector’s AGENTCUBE_AUTH_MODE environment variable, and the auth mode of its registration in the Context Engine (admin console: Connected Systems → the connector → Edit auth). The mode you roll back to depends on the connector’s instance role (see Auth Mode Management → Admin and user connector instances):

  • User / data instance — roll back to a delegated credential, not basic:

    1. In the Context Engine, change the connector registration’s auth mode from internal to delegated_basic and enter the named Oracle user’s username and password.

    2. On the connector, clear any static {PRODUCT}_USERNAME / {PRODUCT}_PASSWORD values (delegated_basic refuses to start while they are set), then set:

      AGENTCUBE_AUTH_MODE=delegated_basic
    3. Restart the connector.

    A user/data instance refuses to start under basic, but delegated_basic is allowed in user mode, so it is the rollback target that keeps the instance running. While rolled back, every call reaches Oracle as that one account, so Oracle enforces and audits that account rather than each user; the Context Engine audit log still records the signed-in user when Context Engine sign-in (AGENTCUBE_CE_AUTH_MODE=oidc) is enabled.

  • Admin-mode connector moved to SSO from basic (AGENTCUBE_CONNECTOR_MODE=admin) — roll back to a shared service account: set {PRODUCT}_USERNAME / {PRODUCT}_PASSWORD for the service account if they are not already present, set AGENTCUBE_AUTH_MODE=basic, update the connector’s Context Engine registration to match, and restart. This applies only when the connector runs AGENTCUBE_CONNECTOR_MODE=admin. A user-mode connector (including an Essbase connector left on its default) refuses to start with basic, so roll it back to delegated_basic as described above.

An admin / metadata instance already runs delegated_basic, not SSO, so an SSO rollback does not affect it.

No image change is required in either case. On some platforms (for example Azure Container Apps) an environment-variable change creates a new revision.

To re-enable SSO later, set AGENTCUBE_AUTH_MODE back to the mode you were running — internal for federated SSO (the current model) or oidc for the earlier per-connector mode — switch the Context Engine registration back to the auth mode it used before, and restart the connector. The SSO environment variables are preserved and take effect on restart.

  • Connector rollbacks are safe — images are immutable and connectors hold no persistent state. Context Engine rollbacks also need the pre-upgrade database backup (see above)
  • Environment variable changes are independent of image versions. If you changed environment variables as part of the upgrade, you may need to revert those as well
  • Container registries retain previous image versions, so rollback images are always available