> ## Documentation Index > Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt > Use this file to discover all available pages before exploring further. # Breaking Changes > Every upgrade action and breaking change, release by release, to check before upgrading Prisme.ai 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](https://docs.prisme.ai/get-started/whats-new.md). > [!TIP] > > **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](https://docs.prisme.ai/self-hosting/operations/updates.md). | Version | What to check | | - | - | | [v27.9.0](#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](#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](#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](#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](#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](#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](#v27-4-3) | **Actions:** Rewrite the Azure OCR configuration as flat keys **Breaking:** Azure OCR secrets are flat keys | | [v27.3.1](#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](#v27-2-4) | **Actions:** Add `image-generation` to the LLM Gateway trusted sources and set the default image model | | [v27.2.2](#v27-2-2) | **Actions:** Check that the LLM Gateway trusts the `storage` workspace | | [v26.03.101144](#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](#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](#v25-11-171950) | **Breaking:** The `${date}` prompt variable only holds the date | | [v25.11.061024](#v25-11-061024) | **Actions:** Update AI Knowledge agents to the new recommended default prompt | | [v25.10.161126](#v25-10-161126) | **Breaking:** Collections run on the new ORM; some behaviours change | **v27.9.0** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **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](https://docs.prisme.ai/products/ai-governance/identity-access.md#permission-format). > 2. **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. > 3. **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](https://docs.prisme.ai/products/ai-governance/model-governance.md#prompt-caching). > 4. **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](https://docs.prisme.ai/products/ai-securechat/dictation.md#for-administrators). > 5. **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](https://docs.prisme.ai/products/agent-factory/embed.md#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](https://docs.prisme.ai/products/ai-governance/identity-access.md#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](https://docs.prisme.ai/products/ai-securechat/dictation.md#for-administrators). * **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](https://docs.prisme.ai/products/agent-factory/embed.md#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](https://docs.prisme.ai/api-reference/authentication.md#active-organization). **v27.8.0** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **Grant the API key permissions.** Add `: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 `:apikeys:*` scope and permissions to the organization API keys and service accounts that manage keys. See [Identity & Access → API Keys](https://docs.prisme.ai/products/ai-governance/identity-access.md#api-keys). > 2. **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. > 3. **Update the clients that display a refusal reason** to read `public_rejection_reason`. > 4. **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 `: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](https://docs.prisme.ai/products/ai-governance/identity-access.md#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. **v27.7.3** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **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](https://docs.prisme.ai/products/ai-governance/model-governance.md#aligning-an-environment-with-the-catalogue). > 2. **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. > 3. **Grant Use Audio Transcriptions** (`llm-gateway:models:audio-transcriptions`) to your custom roles and edited system roles. See [Dictation](https://docs.prisme.ai/products/ai-securechat/dictation.md). > 4. **Add your Git server to `NO_PROXY`** if it has to stay reachable directly. > 5. **Upgrade Redis to 6.2 or later**, or append `?protocol=2` to the crawler's `REDIS_URL` meanwhile. See [Redis → Version compatibility](https://docs.prisme.ai/self-hosting/databases/redis.md#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](https://docs.prisme.ai/products/ai-governance/model-governance.md#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](https://docs.prisme.ai/products/ai-securechat/dictation.md). *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](https://docs.prisme.ai/products/ai-securechat/dictation.md#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](https://docs.prisme.ai/self-hosting/databases/redis.md#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`. **v27.7.1** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **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](https://docs.prisme.ai/self-hosting/operations/updates.md#1-upgrade-the-platform-services). > 2. **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. > 3. **Multi-DNS console: set `WEBAUTHN_RP_ID`** to the common parent domain of your console domains, before users register passkeys. See [Authentication → Configure passkeys](https://docs.prisme.ai/self-hosting/entreprise/authentication.md#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](https://docs.prisme.ai/self-hosting/entreprise/authentication.md#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. **v27.6.3-hotfix** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **Set the `prismeai-workspaces` image tag to `v27.6.3-hotfix`**, and keep every other service on `v27.6.3`. See [Updates → Hotfix images](https://docs.prisme.ai/self-hosting/operations/updates.md#hotfix-images). > 2. **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. **v27.6.2** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **Move embedded chat styling** from the host page CSS to the `customCss` option and `cssVariables`. See [Embed](https://docs.prisme.ai/products/agent-factory/embed.md). > 2. **Self-hosted: exempt `/embed/*`** from any `X-Frame-Options` or `Content-Security-Policy` `frame-ancestors` rule your reverse proxy, WAF or ingress adds. > 3. **Update the automations reading `{{headers['x-prismeai-workspace-id']}}`** to read `{{run.sourceWorkspaceId}}`. See [Automations → Triggers](https://docs.prisme.ai/products/ai-builder/automations.md#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. **v27.4.3** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **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. **v27.3.1** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **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.** **v27.2.4** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **Set up image generation again.** Add `image-generation` to `trusted_source_workspaces` in the LLM Gateway workspace config (`index.yml`): > > ```yaml theme={null} > 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. **v27.2.2** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **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: > > ```yaml theme={null} > config: > value: > trusted_source_workspaces: > - storage > ``` > > Without it, Storage-related features can break. **v26.03.101144** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **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.** **v26.03.021352** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **Allow the modules your Python functions need** with the `PYTHON_BUILTIN_MODULES` [environment variable](https://docs.prisme.ai/self-hosting/entreprise/functions.md#environment-variables). **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`. **v25.11.171950** 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. **v25.11.061024** Actions and breaking changes > [!NOTE] > > **Actions to take** > > 1. **Update your AI Knowledge agents' prompt** to the new recommended default: > > ```yaml theme={null} > 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} > ``` **v25.10.161126** 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](https://docs.prisme.ai/apps-store/marketplace/collection.md#release-note%3A-collection-with-postgresql). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.