Breaking Changes

This page gathers, release by release, what to check before upgrading Prisme.ai. Each release lists first the actions to take — permissions to grant, configuration to update, charts to upgrade — then the breaking changes, behaviours that change for your users or your integrations and why. The full release notes stay in What’s New.

Upgrading across several releases? Read every section between your current version and the target one, and apply the actions from the oldest to the newest. For the upgrade procedure itself, see Updates.

Version	What to check
v27.9.0	Actions: Grant `account:access-tokens:use` and `account:demo-mode:use` to custom and edited roles; Add `agent-evaluations` to the LLM Gateway `trusted_source_workspaces`; Run Update from catalogue on the Models page; Decide whether to keep the browser dictation fallback, on by default; Add `data-lang="en"` to embedded chats that must stay in English Breaking: Personal access tokens and demo mode are gated by role permissions; The legacy `/v1/files` and `/v1/vector_stores` storage routes are removed; Without a transcription model, dictated audio goes to the browser’s speech service; The embedded chat follows the visitor’s language
v27.8.0	Actions: Grant the `apikeys` permissions to custom and edited roles; Create the Agent Evaluations organization API key (`AGENT_FACTORY_API_KEY`); Make refusal-reason clients read `public_rejection_reason`; Split documents over 10,000 chunks, or tune `max_chunks_per_document` Breaking: Managing API keys moved to dedicated `apikeys` permissions; A document over 10,000 chunks fails to index; `rejection_reason` is empty for most readers; Stalled or nightly evaluation runs need an organization API key; Access to knowledge bases and canvases is tighter
v27.7.3	Actions: Set `supports_forced_tool_choice: false` on the models that reject it; Reconfigure the Tableau, ServiceNow and SonarQube instances; Grant Use Audio Transcriptions to custom roles; Add your Git server to `NO_PROXY` if needed; Upgrade Redis to 6.2+, or set `?protocol=2` on the crawler Breaking: Tableau, ServiceNow and SonarQube agents stop working until reconfigured; Dictation needs a role permission; Git goes through `HTTPS_PROXY`; The crawler refuses Redis older than 6.0
v27.7.1	Actions: Upgrade Helm `prismeai-apps` `0.7.2` and `prismeai-core` `1.12.2`; Enable `authentication.allowApiKeyOnly` for Code Interpreter download links; Set `WEBAUTHN_RP_ID` on a multi-DNS console Breaking: Some monday.com, Outlook, Power BI and GitLab users reconnect once; Indexing embeddings count against the monthly LLM budget
v27.6.3-hotfix	Actions: Set the `prismeai-workspaces` image to `v27.6.3-hotfix`; Re-run the platform pull of the `base2` group
v27.6.2	Actions: Move embedded chat styling to `customCss` and `cssVariables`; Self-hosted: exempt `/embed/` from `X-Frame-Options` and `frame-ancestors`; Read `run.sourceWorkspaceId` instead of the `x-prismeai-workspace-id` header Breaking:* Host page CSS no longer styles the embedded chat; `x-prismeai-` headers are removed before webhook automations run
v27.4.3	Actions: Rewrite the Azure OCR configuration as flat keys Breaking: Azure OCR secrets are flat keys
v27.3.1	Actions: Send `target_agent_id` to update an agent through the import API Breaking: Without `target_agent_id`, the import API creates a new agent
v27.2.4	Actions: Add `image-generation` to the LLM Gateway trusted sources and set the default image model
v27.2.2	Actions: Check that the LLM Gateway trusts the `storage` workspace
v26.03.101144	Actions: Add the `slug:` prefix to webhook and WebSocket calls by slug Breaking: Calls by slug without `slug:` fail
v26.03.021352	Actions: Allow the Python modules you need with `PYTHON_BUILTIN_MODULES` Breaking: Python functions can no longer import `os`, `sys`, `subprocess` and other modules by default
v25.11.171950	Breaking: The `${date}` prompt variable only holds the date
v25.11.061024	Actions: Update AI Knowledge agents to the new recommended default prompt
v25.10.161126	Breaking: Collections run on the new ORM; some behaviours change

Actions and breaking changes

Actions to take

Grant the access token and demo mode permissions. Add account:access-tokens:use and account:demo-mode:use (under Account (Settings)) to your custom roles, to the default roles your organization has edited, and, on self-hosted deployments, to the roles declared in ORG_ADDITIONAL_SYSTEM_ROLES. See Identity & Access → Permission Format.
Trust agent-evaluations in the LLM Gateway. On each environment, add agent-evaluations to trusted_source_workspaces in the LLM Gateway workspace config, and check that agent-evaluations has registerWorkspace: true. Without it, evaluations run by non-admin users stay unjudged.
Run Update from catalogue on the Models page after the upgrade. Strongly recommended: it flags the Claude models that do not accept the instructions an agent gives itself mid-answer. See Model Governance → Prompt caching.
Decide on browser dictation. To keep dictated audio within your providers, make a transcription model available to every user who dictates, or turn off Allow browser dictation fallback in Agents Controls › Models, or Browser dictation fallback in Govern › Models › Providers › Defaults — in particular on self-hosted installations without a transcription model. See Dictation.
Keep embedded chats in English if needed by adding data-lang="en" (or lang: 'en' in mount()) to the integration. See Embed your agent → Language.

Breaking changes

Personal access tokens and demo mode now need a role permission. Personal access tokens — also used by the Builder MCP, the SDK and the browser extension — and demo mode are controlled by two permissions, account:access-tokens:use and account:demo-mode:use, under Account (Settings). The default roles keep them, but if your organization uses custom roles or has edited a default role, add these permissions to the roles that need them, otherwise their members can no longer create or use access tokens in your organization. Self-hosted deployments using ORG_ADDITIONAL_SYSTEM_ROLES must add them to those roles. A token is checked in the organization each request runs in, not the organization a workspace belongs to: members of several organizations should send the x-prismeai-org-slug header, otherwise their first organization applies, and a refusal there blocks the token everywhere, DSUL fetch calls and scheduled automations included. See Identity & Access → Permission Format.
The legacy /v1/files and /v1/vector_stores storage routes are removed. DELETE /v1/files/{id} stays. Use /v1/knowledge_bases and the Storage workspace file upload instead. Only the user who uploaded a file can now add it to a knowledge base, and only platform administrators can delete another user’s file.
Dictation falls back to the browser’s speech service on desktop Chrome and Edge when there is no transcription model. If your organization has no transcription model, or its allowed models leave it out, users can dictate again in desktop Chrome and Edge. Visitors not signed in to an embedded chat get this too, but only when the organization has no model. Their audio goes to Google (Chrome) or Microsoft (Edge), not to Prisme.ai, outside your providers, governance and data residency. Roles without Use Audio Transcriptions still cannot dictate when a transcription model exists. The fallback is on by default. To keep dictated audio within your providers, make a transcription model available to every user who dictates, or turn off Allow browser dictation fallback in Agents Controls › Models for your organization, or Browser dictation fallback in Govern › Models › Providers › Defaults for the whole platform — in particular on self-hosted installations without a transcription model. Changes apply when users reload the chat. See Dictation.
The embedded chat now follows the visitor’s language. It no longer always shows in English. Existing integrations switch without any action: add data-lang="en" (or lang: 'en' in mount()) to keep English, or set another language with the same option. See Embed your agent → Language.

Deprecation

PUT /v2/user/active-org is deprecated and will be removed in a later release. Send the x-prismeai-org-slug header with each request instead. See Authentication → Active Organization.

Actions and breaking changes

Actions to take

Grant the API key permissions. Add <product>:apikeys:read, :create and :delete (for agent-factory, storage, ai-collection-v3) to your custom roles, to the default roles your organization has edited, and to ORG_ADDITIONAL_SYSTEM_ROLES. Give the <product>:apikeys:* scope and permissions to the organization API keys and service accounts that manage keys. See Identity & Access → API Keys.
Create the Agent Evaluations API key. In the organization that owns the evaluated agents, create an organization API key with permissions agent-factory:agents:read and llm-gateway:models:chat-completions and scopes agent-factory:agents:* and llm-gateway:models:*, store it in the agent-evaluations workspace secret AGENT_FACTORY_API_KEY, and restrict the nightly batch to that organization before re-enabling it.
Update the clients that display a refusal reason to read public_rejection_reason.
Split documents over 10,000 chunks, or raise max_chunks_per_document (10,000 at most) and embedding_batch_size in the Storage workspace config.

Breaking changes

Managing API keys now needs its own permissions. Listing, creating, rotating and revoking the API keys of an agent, a knowledge base or a collection moved out of the sharing permissions into <product>:apikeys:read, :create and :delete, for agent-factory, storage and ai-collection-v3. They are enforced even on resources the user owns. The default roles keep them, but custom roles, default roles your organization has edited, and roles defined through ORG_ADDITIONAL_SYSTEM_ROLES lose access until an administrator grants the new permissions. Organization API keys scoped to agents, knowledge bases or collections can no longer create, rotate or revoke keys without the matching apikeys scope and permissions. See Identity & Access → API Keys.
A document over 10,000 chunks now fails to index. Large documents are indexed batch by batch instead of staying stuck in progress when the worker runs out of memory, and anything above the cap fails with DocumentTooLarge — including a document indexed before, the next time it is indexed or refreshed. Split the file, or move the cap with max_chunks_per_document (10,000 at most) and embedding_batch_size in the Storage workspace config.
rejection_reason is now empty for most readers. The raw reason an ingestion hook gave for refusing a document is served only to the knowledge base’s owners and to storage or platform administrators. Everyone else reads the new public_rejection_reason field, so a client that displays a refusal reason must be updated. The refusal stays recorded when the document is reindexed.
Agent Evaluations need an organization API key. Runs started by the nightly cron, or resumed after a stall, now authenticate with one. Create it in the organization that owns the evaluated agents, with permissions agent-factory:agents:read and llm-gateway:models:chat-completions and scopes agent-factory:agents:* and llm-gateway:models:*, then store it in the agent-evaluations workspace secret AGENT_FACTORY_API_KEY. Without it a stalled run fails with EVAL_AUTH_NOT_CONFIGURED and the nightly batch stops. The key only reaches agents of its own organization, so restrict the nightly batch to that organization before re-enabling it.
Access to knowledge bases and canvases is tighter. A knowledge base no longer serves read access to users who hold no right on it. An agent now only reaches the canvases of the user it is talking to. A knowledge base can only be attached to an agent by someone who can read it, and only when it belongs to the agent’s organization — on import, the bases that fail those conditions are removed from the agent’s tools and reported.

Actions and breaking changes

Actions to take

Declare the models that reject a forced tool choice. Set provider_config.supports_forced_tool_choice: false on Claude Opus 5.5, Fable 5.1, Mythos 5.1 and DeepSeek reasoner, from Govern › Models or by aligning the environment with the catalogue. See Model Governance → Aligning an environment with the catalogue.
Reconfigure Tableau, ServiceNow and SonarQube. For each installed instance, check the Authentication tab of its configuration page, then in the Agents tab tick the authorized agents and click Install the capability on each.
Grant Use Audio Transcriptions (llm-gateway:models:audio-transcriptions) to your custom roles and edited system roles. See Dictation.
Add your Git server to NO_PROXY if it has to stay reachable directly.
Upgrade Redis to 6.2 or later, or append ?protocol=2 to the crawler’s REDIS_URL meanwhile. See Redis → Version compatibility.

Breaking changes

Declare the models that reject a forced tool choice. The upgrade does not set it for you: in the model catalog, set provider_config.supports_forced_tool_choice: false on Claude Opus 5.5, Fable 5.1, Mythos 5.1 and DeepSeek reasoner. Without it, every message with a selected tool fails once on those models, and fails for good on streamed Vertex and Bedrock SDK requests. You can set it from Govern › Models (Provider Config › Accepts forced tool choice), let the model Test button detect it, or align the whole environment with the reference catalogue. See Model Governance → Aligning an environment with the catalogue.
Tableau, ServiceNow and SonarQube agents stop working until you reconfigure them. These three connectors are now configured from the connector configuration page and only accept the agents you authorize there. For each installed instance: open its configuration page, check the credentials carried over in the Authentication tab, then in the Agents tab tick the authorized agents and click Install the capability on each, which replaces the old address and API key — both now refused. Automations that call these connectors without going through an agent keep working untouched.
Grant the dictation permission to your custom roles. Chat dictation requires Use Audio Transcriptions (llm-gateway:models:audio-transcriptions). The system Member, Agent Maker and Builder roles hold it by default, but custom roles — and system roles your organization has already edited — do not. Add it in Governance → Roles, otherwise their holders never see the microphone. See Dictation. This still holds when a transcription model exists. Since then, when there is no transcription model at all, desktop Chrome and Edge fall back to the browser’s own speech service: see Dictation → For administrators.
Git now goes through HTTPS_PROXY. If your Git server has to stay reachable directly, add it to NO_PROXY.
The crawler needs Redis 6.0 or later. prismeai-crawler now opens its Redis connections with the RESP3 protocol, which an older Redis rejects: the crawler then stops at startup with unknown command HELLO. Redis 6.2 is the supported minimum, see Redis → Version compatibility. Until your Redis is upgraded, append ?protocol=2 to the crawler’s REDIS_URL, for example redis://redis:6379/0?protocol=2. The parameter is ignored when REDIS_TLS_CA_FILE is set: unset that variable and pass the certificate in the URL instead, rediss://redis:6380/0?protocol=2&ssl_ca_certs=/path/to/ca.pem.

Actions and breaking changes

Actions to take

Upgrade Helm prismeai-apps to 0.7.2. The prismeai-functions liveness probe now writes to the volume, and its former 1 second timeout puts the functions API in a restart loop on a slow NFS. If you are not upgrading the chart, set prismeai-functions.livenessProbe.timeoutSeconds: 3 yourself. See Upgrade the platform services.
Upgrade Helm prismeai-core to 1.12.2 and enable authentication.allowApiKeyOnly in the upload block of the api-gateway ConfigMap, for Code Interpreter download links.
Multi-DNS console: set WEBAUTHN_RP_ID to the common parent domain of your console domains, before users register passkeys. See Authentication → Configure passkeys.

Breaking changes

Some users have to reconnect their account once. The OAuth token change below invalidates the existing connections of monday.com users, and of part of the Outlook, Power BI and GitLab users. They are prompted to reconnect, and nothing else is lost.
Passkeys need no configuration on a single-domain console. A console served over https on one domain — the usual case, sandbox and staging included — enables them by itself, with no environment variable to set. A multi-DNS infrastructure does need one: when the console answers on several domains, say studio.prisme.example.com and admin.prisme.example.com, set WEBAUTHN_RP_ID to their common parent domain, here prisme.example.com. Without it the gateway starts with passkeys off and merely logs a warning — the same happens on a console not served over https. Set the RP ID early either way: changing it later makes every passkey already registered unusable. See Authentication → Configure passkeys.
Indexing embeddings now count against the organization’s monthly LLM budget. They were not counted at all before, so an organization with a capped budget can reach it earlier than it used to. Periods before the fix are not recalculated.

Actions and breaking changes

Actions to take

Set the prismeai-workspaces image tag to v27.6.3-hotfix, and keep every other service on v27.6.3. See Updates → Hotfix images.
Re-run the platform pull of the base2 group. The four fixed workspaces (Conversations Service, Conversations Service App, Teams Service, Teams Service App) are reported as imported, everything else as skipped. Without it, every conversation fails to start since v27.6.

Actions and breaking changes

Actions to take

Move embedded chat styling from the host page CSS to the customCss option and cssVariables. See Embed.
Self-hosted: exempt /embed/* from any X-Frame-Options or Content-Security-Policy frame-ancestors rule your reverse proxy, WAF or ingress adds.
Update the automations reading {{headers['x-prismeai-workspace-id']}} to read {{run.sourceWorkspaceId}}. See Automations → Triggers.

Breaking changes

Host page CSS no longer styles the embedded chat. The widget now runs as an isolated iframe.
The embedded chat is served from the console’s /embed/* pages inside an iframe. A rule adding X-Frame-Options or frame-ancestors to every response blocks it, and the browser shows a “can’t open this page” error instead of the chat.
Headers starting with x-prismeai- are removed before a webhook automation runs, x-prismeai-workspace-id included.

Actions and breaking changes

Actions to take

Rewrite the Azure OCR connector configuration as flat keys if it is still JSON-shaped.

Breaking changes

Azure OCR connector secrets moved from a JSON structure to flat keys, so they can be sourced from Azure Key Vault.

Actions and breaking changes

Actions to take

Send target_agent_id when updating an existing agent from a .md file through the Agent Creator import API.

Breaking changes

The import API creates a new agent unless target_agent_id is provided.

Actions and breaking changes

Actions to take

Set up image generation again. Add image-generation to trusted_source_workspaces in the LLM Gateway workspace config (index.yml):
config: value: trusted_source_workspaces: - storage - image-generation - agent-factory
Then, in AI Governance › Agents Controls, set default_image_generation_model and add the new default-image-model field where required.

Actions and breaking changes

Actions to take

Make the LLM Gateway trust the Storage workspace. If the LLM Gateway workspace config was preserved during the upgrade (not overwritten, which some setups do on purpose to keep custom values), make sure its index.yml contains:
config: value: trusted_source_workspaces: - storage
Without it, Storage-related features can break.

Actions and breaking changes

Actions to take

Add the slug: prefix to the webhooks and WebSockets you call by slug, for example /v2/workspaces/slug:ops-manager/webhooks/user.

Breaking changes

Calling webhooks and WebSockets by slug requires the slug: prefix.

Actions and breaking changes

Actions to take

Allow the modules your Python functions need with the PYTHON_BUILTIN_MODULES environment variable.

Breaking changes

Python functions can no longer import some standard library modules by default: subprocess, os, sys, shutil, socket, ctypes, multiprocessing, _thread, signal, resource, importlib, runpy, code, ast, dis, pickle, marshal, pty, fcntl, mmap, gc, inspect, webbrowser, ensurepip, venv.

Actions and breaking changes

Breaking changes

AI Knowledge: the ${date} prompt variable only holds the date, YYYY-MM-DD, without the hour, minutes, seconds and microseconds.

Actions and breaking changes

Actions to take

Update your AI Knowledge agents’ prompt to the new recommended default:

prompt:
  keyword: ${context}
  default: |-
    You are a helpful and knowledgeable assistant.

    Use the available tools to answer the user's query as accurately as possible.
    The documents_rag tool is very important as it allows you to search through a knowledge base built for you.

    If the context contains relevant information, base your answer on it and make clear references to it.
    If the context is incomplete or missing, answer to the best of your knowledge but clearly state that the information is not in the provided context.
    Never invent or fabricate details that cannot be supported by either the context or your prior knowledge.

    Keep answers clear, concise, and directly relevant to the query.

    The current date is : ${date}

Actions and breaking changes

Breaking changes

Collections run on the new ORM, compatible with MongoDB and PostgreSQL. Some behaviours change, see Collection → Release note: Collection with PostgreSQL.

Overview

First Steps