Rollbacks
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).
Rollback Procedure
Section titled “Rollback Procedure”1. Identify the Previous Version
Section titled “1. Identify the Previous Version”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.
2. Deploy the Previous Version
Section titled “2. Deploy the Previous Version”The examples below roll back the Essbase connector (agentcube-essbase). The same commands apply to agentcube-planning and agentcube-fccs.
az containerapp update --name {app_name} --resource-group {resource_group} --image ghcr.io/caprusai/agentcube-essbase:{previous_version} --revision-suffix "rollback-{timestamp}"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).
Register a new task definition revision pointing to the previous image tag, then force a redeployment:
aws ecs update-service --service agentcube-essbase --task-definition agentcube-essbase:{previous_revision} --force-new-deployment --region {region}aws ecs update-service \ --service agentcube-essbase \ --task-definition agentcube-essbase:{previous_revision} \ --force-new-deployment \ --region {region}Update the image tag in your docker-compose.yml to the previous version, then restart (the command is the same in PowerShell and bash):
docker compose up -d agentcube-essbaseOr with a plain Docker run, stop the current container and start a new one with the previous tag. The command matches the on-premise install: it joins the agentcube network so the Context Engine can reach the connector at http://agentcube-essbase:8080, and publishes on 127.0.0.1:8081 because the Context Engine already holds host port 8080. The env file /etc/agentcube/essbase.env holds the same variables as the original run: AGENTCUBE_CONNECTOR_MODE=admin, AGENTCUBE_AUTH_MODE=delegated_basic and ESSBASE_SERVER_URL (create it with those values if you originally passed them with -e flags).
docker stop agentcube-essbasedocker rm agentcube-essbasedocker run -d --name agentcube-essbase --restart unless-stopped --network agentcube -p 127.0.0.1:8081:8080 --env-file /etc/agentcube/essbase.env ghcr.io/caprusai/agentcube-essbase:{previous_version}docker stop agentcube-essbasedocker rm agentcube-essbasedocker run -d --name agentcube-essbase --restart unless-stopped \ --network agentcube \ -p 127.0.0.1:8081:8080 \ --env-file /etc/agentcube/essbase.env \ ghcr.io/caprusai/agentcube-essbase:{previous_version}Roll back to the previous deployment revision (the commands are the same in PowerShell and bash):
kubectl rollout undo deployment/agentcube-essbase -n agentcubeOr deploy a specific previous version:
kubectl set image deployment/agentcube-essbase agentcube-essbase=ghcr.io/caprusai/agentcube-essbase:{previous_version} -n agentcubeDelete the current instance and recreate it using the previous image tag and the original creation parameters.
3. Verify
Section titled “3. Verify”Invoke-RestMethod https://{connector_hostname}/healthcurl https://{connector_hostname}/healthConfirm version shows the previous version and status is healthy.
4. Test
Section titled “4. Test”Run a tool call from your AI platform to verify end-to-end functionality.
Rolling Back the Context Engine
Section titled “Rolling Back the Context Engine”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):
- Restore the pre-upgrade backup (snapshot or
pg_dump) of the Context Engine PostgreSQL database. - Deploy the previous
ghcr.io/caprusai/agentcube-ce:{previous_version}image with the same environment settings and the sameAGENTCUBE_CE_CREDENTIAL_KEY, using the commands above. - Verify with
GET https://{ce_hostname}/healthand 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.
Rolling Back SSO
Section titled “Rolling Back SSO”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:-
In the Context Engine, change the connector registration’s auth mode from
internaltodelegated_basicand enter the named Oracle user’s username and password. -
On the connector, clear any static
{PRODUCT}_USERNAME/{PRODUCT}_PASSWORDvalues (delegated_basicrefuses to start while they are set), then set:AGENTCUBE_AUTH_MODE=delegated_basic -
Restart the connector.
A user/data instance refuses to start under
basic, butdelegated_basicis 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}_PASSWORDfor the service account if they are not already present, setAGENTCUBE_AUTH_MODE=basic, update the connector’s Context Engine registration to match, and restart. This applies only when the connector runsAGENTCUBE_CONNECTOR_MODE=admin. Auser-mode connector (including an Essbase connector left on its default) refuses to start withbasic, so roll it back todelegated_basicas 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