> For the complete documentation index, see [llms.txt](https://docs.frends.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frends.com/release-notes/frends-6.4/breaking-changes.md).

# Breaking Changes

Changes that require action before updating to Frends 6.4.

This page lists the breaking changes introduced in Frends 6.4 releases, including changes from earlier versions that are repeated here for visibility. Breaking changes may require action from you before or during an update, such as reconfiguring settings or adjusting running integrations.

{% hint style="warning" %}
Always review the breaking changes for your target version before starting an update. Updating without accounting for breaking changes may affect running integrations and Agent compatibility.

Self-hosted Agents with an SQL database also require a database schema update through the database initializer.
{% endhint %}

{% hint style="warning" %}
Updating to 6.4 from earlier versions requires running the database initializer; see [Database schema update](https://docs.frends.com/release-notes/frends-6.4/breaking-changes.md#breaking-changes-in-version-640).
{% endhint %}

## .NET Runtime version update

On-premises Cross-Platform Agents for Frends version 6.4 onwards require .NET Runtime 10.0.7 or newer to be installed.

The Windows Agent and Management Web Portal require the .NET 10 hosting bundle to be installed.

Cloud Agents and Compliant Cloud images include .NET 10 out of the box.

## Breaking changes in Version 6.4.0 <a href="#breaking-changes-in-version-640" id="breaking-changes-in-version-640"></a>

### Legacy Agent removed <a href="#legacy-agent-removed" id="legacy-agent-removed"></a>

The Legacy Agent and its installer are no longer included, and Processes can no longer be compiled for the .NET Framework 4.7.1 or .NET Standard 2.0 targets. Tenants that still have Legacy Agents in use will not be updated to Frends 6.4. Move every Agent Group that still runs the Legacy Agent to the Cross-platform Agent before updating; see [Updating from Legacy Frends](https://docs.frends.com/guides/setup-and-installation/updating-from-legacy-frends.md). A Process saved for one of the removed targets is compiled for .NET 10 the next time it is saved, and a Process version compiled for .NET Framework 4.7.1 can no longer be deployed.

### Database schema update <a href="#database-schema-update" id="database-schema-update"></a>

Frends 6.4 adds database tables for certificate management and removes the database step logging tables.&#x20;

Run the database initializer for the ConfigurationStore and LogStore databases as part of the update.

### Agent configuration on Azure Service Bus

Agents on Azure Service Bus get their Service Bus access tokens from the Web Portal at startup with a bootstrap key, as they do from 6.3.3.&#x20;

When updating from 6.3.2 or earlier, download each Agent together with its configuration, or the Kubernetes deployment files, again. Agents of earlier versions continue to connect to Service Bus as before, and Agents on RabbitMQ are not affected; see [Agent configuration on Azure Service Bus](https://docs.frends.com/release-notes/frends-6.4/breaking-changes.md#breaking-changes-in-version-633) in the Frends 6.3 breaking changes.

### Step logging to the database removed <a href="#step-logging-to-the-database-removed" id="step-logging-to-the-database-removed"></a>

Process step data is always logged to blob storage, and the Agent Group option to log steps to the database has been removed together with the step tables in the LogStore database. Step data logged to the database before the update is no longer available. The always empty `Steps` list has also been removed from the Process instance details response of the Frends Platform API.

### Shape parameters in Process logs <a href="#shape-parameters-in-process-logs" id="shape-parameters-in-process-logs"></a>

Every shape now logs its parameters at the default Info log level, not only at Debug, and a failed step logs the parameters it was called with. At Info, logged parameters are cut to 2,000 characters per value and 20 items per list; results and promoted values keep their existing limits. Expect more step data per Process instance. Use the **Skip logging result and parameters** option on a shape whose parameters should not be logged. This applies to a Process once a new version of it has been saved and deployed after the update; Process versions saved before the update keep logging as before.

### Masked values in Process logs <a href="#masked-values-in-process-logs" id="masked-values-in-process-logs"></a>

Values of secret Environment Variables, secret Process Variables and secret Manual Trigger parameters are masked in Process logs, and so are the credential headers, cookies and query parameters of HTTP and API Trigger requests listed in the new Agent setting `TriggerHeadersToMask`. Its default list is `Authorization`, `Cookie`, `X-Api-Key`, `X-ApiKey`, `X-Auth-Token` and `Proxy-Authorization`. Names are matched without regard to case, against both request headers and query parameters. Listing `Cookie` masks the value of every cookie of the request, and the header or query parameter that an API Policy reads its API key from is always masked. The masking applies to a Process once a new version of it has been saved and deployed after the update; Process versions saved before the update keep logging as before.

### Log Service and database initializer logging <a href="#log-service-and-database-initializer-logging" id="log-service-and-database-initializer-logging"></a>

log4net and its `log4net.config` files have been removed. The Log Service writes its log file through the `Logging` section of its `appsettings.json`, where `PathFormat`, `RetainedFileCountLimit` and `FileSizeLimitBytes` set the file name, the number of files kept and the file size. Move any customisation of the Log Service `log4net.config` there. The database initializer now writes its log to the console only.

### Forwarded headers on the Agent <a href="#forwarded-headers-on-the-agent" id="forwarded-headers-on-the-agent"></a>

The Agent now honours `X-Forwarded-Host` and `X-Forwarded-Proto` only from trusted proxies when it builds the URLs it returns for OpenAPI documents, the MCP Trigger and its OAuth discovery. By default, proxies on loopback and private networks are trusted. The RFC 7239 `Forwarded` header is no longer read. If your proxy uses a public address, add it to `ForwardedHeaders:KnownProxies` or `ForwardedHeaders:KnownNetworks` in the Agent `appsettings.json`. HTTP Trigger requests are not affected unless `ForwardedHeaders:ApplyToAllRequests` is set to `true`.

### HTTP log of unauthenticated and unmatched requests <a href="#http-log-of-unauthenticated-and-unmatched-requests" id="http-log-of-unauthenticated-and-unmatched-requests"></a>

The Agent now logs requests that fail authentication or match no endpoint in full only up to 10 per minute for each endpoint, declared HTTP method and status code, and up to 100 per minute in total. The rest are summarised as one HTTP log entry per endpoint, declared HTTP method and status code each minute, with the number of requests in its path. Monitoring or log processing that counts individual rejected requests from the HTTP log should count the summary entries too. The limits can be changed with `HttpLoggingOptions:UnauthenticatedRequestsPerEndpointPerMinute` and `HttpLoggingOptions:UnauthenticatedRequestsPerAgentPerMinute` in the Agent `appsettings.json`.

## Breaking changes in Version 6.3.3 <a href="#breaking-changes-in-version-633" id="breaking-changes-in-version-633"></a>

### Agent configuration on Azure Service Bus

On Azure Service Bus, the downloaded Agent configuration and the Kubernetes deployment files no longer contain Service Bus SAS tokens. They contain a bootstrap key (`BootstrapKey`) instead, which the Agent redeems with the Web Portal on every startup for the tokens it needs, and stores the tokens locally. To update an Agent on Service Bus, download the Agent together with its configuration; for Kubernetes, download the deployment files again on the first update to 6.3.3. An Agent without a bootstrap key stops with an error that says to download its configuration again, and so does an Agent that cannot reach the Web Portal on its first startup. Agents of earlier versions continue to connect to Service Bus as before with the tokens in their existing configuration, since the queues stay the same. Do not give them a newly downloaded configuration: they cannot use the key, and it has no tokens.

A bootstrap key can be used once. It keeps working for 60 minutes after its first use so that a failed startup can be retried; the Web Portal setting `AgentBootstrapKeyGracePeriodMinutes` changes this and is not in the shipped `appsettings.json`. Downloading the Agent installation or configuration files again replaces the key, and an Agent that already stored its tokens keeps working with them. Agent Groups in Kubernetes Deployment or StatefulSet registration mode share one reusable key: downloading the Kubernetes deployment files again returns the same key, and the 60-minute grace period does not apply to it. Kubernetes Agent names cannot contain `_`.&#x20;

This change does not affect Agents on RabbitMQ.

### API Policy public access <a href="#api-policy-public-access" id="api-policy-public-access"></a>

Public access on an API Policy now applies only to the Agent Groups selected for public access. Before 6.3.3, an Agent Group that received the policy for another reason, such as an OAuth identity, an API key or request logging, also accepted requests without credentials. Callers that relied on this start receiving 401 or 403 responses once the corrected policies reach the Agents, which happens automatically on each Agent's next heartbeat after the update. Select the Agent Groups explicitly for public access where anonymous access is intended.

### API Policies and Environment rules <a href="#api-policies-and-environment-rules" id="api-policies-and-environment-rules"></a>

Users whose Environment rules exclude an Environment that an API Policy targets no longer see that policy at all, and cannot update or delete it. This includes the default request logging policies, which target every cross-platform Agent Group.

### IP allowlists and IPv6 callers <a href="#ip-allowlists-and-ipv6-callers" id="ip-allowlists-and-ipv6-callers"></a>

IPv6 callers are no longer matched against IP allowlists through a reverse DNS lookup to an IPv4 address. An IPv6 caller now matches only an IPv6 entry in `PlatformJwtAllowedIps` or in an OAuth provider's allowed networks, such as `{ "IpAddress": "2001:db8::/32" }`. IPv4 callers, including IPv4-mapped addresses on dual-stack servers, are not affected. A rejected caller now receives a standard problem details response body instead of a plain text message.

### Gateway Agents and API Passthrough Triggers <a href="#gateway-agents-and-api-passthrough-triggers" id="gateway-agents-and-api-passthrough-triggers"></a>

`TimeoutMinutesForGateway` now limits how long the Agent waits for the backend's response headers and then each wait for more of the response body, instead of the whole response. A long-running response that keeps sending data is no longer cut off, and a backend that stops sending after its headers have been passed on is cut off by closing the connection to the caller instead of a 504 response.

### Frends MCP <a href="#frends-mcp" id="frends-mcp"></a>

The `deploy_process` tool replaces the `activateTriggers` argument with a required `activation` argument: `activate` for the previous `true`, `keep` for the previous `false`, or the new `deactivate`.

## Breaking changes in Version 6.3.2

### Log Service on S3 storage

**L**og retention now uses S3 lifecycle rules by default instead of batch deletion. If your object store does not support lifecycle rules, such as Oracle OCI, turn the lifecycle option off in the Log Service configuration.

### Agent log configuration

The per-Process log file of the cross-platform Agent uses a new log category. Only deployments that have customised the Agent logging configuration need to update the category name; [see the full release notes](https://docs.frends.com/release-notes/frends-6.3/version-6.3.2.md).

### Role management

The extra checks added in 6.3.1 on which rules an administrator may put into a role have been removed. Managing roles still requires user management administrator rights.

## Breaking changes in Version 6.3.1

### Kubernetes StatefulSet Agent groups

The 6.3.1 StatefulSet template adds per-pod persistent volumes (`volumeClaimTemplates`), which Kubernetes does not allow to be changed in place. A StatefulSet created before 6.3.1 must be deleted with `kubectl delete statefulset <name> --cascade=orphan` (its pods keep serving) and re-applied. See the README included in the Kubernetes configuration download.

### HTTP Triggers and client certificates

The Agent setting `EnableClientCertificateValidation` is now tri-state. When it is not set (the new default), the Agent requests a client certificate from HTTPS callers only when at least one HTTP Trigger requires certificate authentication. Set it explicitly to `true` or `false` to force the previous always-on or always-off behaviour.

### Audit log

Failed and denied requests (4xx/5xx) are now audit-logged by default, which increases audit log volume. Set `EnableAuditLoggingForFailedRequests` to `false` to keep the previous behaviour.

### Database Initializer

the `--doNotEnableSnapshotIsolation` parameter has been removed. `READ_COMMITTED_SNAPSHOT` and `ALLOW_SNAPSHOT_ISOLATION` are now always enabled on SQL Server databases.

## Breaking changes in 5.8 and earlier

{% hint style="info" %}
These following changes were already present in 5.8 and are listed here for visibility.
{% endhint %}

## API Policy migration

We've strived to make the update and migration process as smooth as possible, but due to difference in the configuration model for the new API Policy based authentication and authorization, the following should be noted:

* An API Process which has OAuth in the OpenAPI Specification and it's path is included in the API Key rulesets was previously only accessible through OAuth, but now it will be accessible with both authentication methods because it had a matching API Key ruleset. This can be reconfigured by modifying the API Policy
* API Policy configuration replaces earlier API Key usage methods where the API Key had to be sent in `Authorization: Apikey` or `x-apikey` headers or in header specified in API Specification, with configurable header for API Keys. As a fallback, these old configurations can also be read if no API Policy configuration exists for the API Key.
* The update and migration might be blocked if there are inconsistencies between the OpenAPI Specification and Process deployments

## Legacy Agent

We strongly recommend updating to the Cross-platform Agent to be able to use the latest technology and solutions possible. Some features will not be supported by it, like the HTTP monitoring which was released in Frends 5.7.

* Legacy Agent are being retired. Frends version 6.4 will be the first version to no longer support the Legacy Agent

{% hint style="info" %}
The following changes were already present in 5.7 and are listed here for visibility.
{% endhint %}

## Frends Platform API changes (for pre 5.7 installations)

The Frends Platform API has been now released and the old v0.9 path has been retired, so you will need to update any calls to the API to target the new v1 path. Also the error result for the API calls has been changed, otherwise the APIs will work the same way as before. Also there are changes to the internal API which is not fully supported for outside use, so if you have used that, you will need to verify everything works separately.

​[You can learn more about the Frends Platform API here](https://docs.frends.com/reference/frends-platform-api/introduction.md).

## Frends Agent container image path changed

The path for the assemblies inside of the container image is now /app. If there are modifications to the official container image, the new path should be taken into account.

## Agents required to have access to the UI

The Agents now fetch their Process and Task packages through the UI, so firewalls on the Agents need to allow outbound access to the Frends UI: \<tenant>.frendsapp.com on port 443.

## Agent bundled installation LocalDB requires Visual C++ Redistributable (Frends 5.7.3+)

Because the bundled LocalDb for the Legacy Agent was updated, you will need to install Visual C++ 2019 redistributable before installing the bundle. The installer available from here: <https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170>

## OpenId Connect (SSO)

Customers using Microsoft Entra ID (formerly Azure AD) as an OpenID login provider for their Frends Tenant must update the App Registration in Azure.

In the Azure portal, go to **Manage → Authentication** and modify the App Registration's **Redirect URI**.

Starting with Frends 5.7, the Redirect URI must include an OIDC suffix: `signin-oidc-[Application ID]`.

Example (Frends 5.6 or earlier):

* Redirect URI: `https://myfrendstenant.frendsapp.com`
* Application ID: `3e89b538-f75c-42b5-96f1-402f1ac0a549`

Updated Redirect URI for Frends 5.7+:\
`https://myfrendstenant.frendsapp.com/signin-oidc-3e89b538-f75c-42b5-96f1-402f1ac0a549`

{% hint style="warning" %}
**Use your own Application ID**, obtained from Azure Portal for your Application registration, instead of the example value. The example value will not work for you.
{% endhint %}

You can add the new URI in advance **as an additional URI** to the App Registration to ensure functionality before and after the update.

**Do not remove or modify the current Redirect URI** until Frends is updated to 5.7+, as the new format is incompatible with earlier versions.

No changes are needed in the Frends UI.

{% hint style="info" %}
These following changes were already present in 5.5 and are listed here for visibility.
{% endhint %}

## Service Bus for Windows (for pre 5.5 installations)

Support for Service Bus for Windows Server is removed, when updating to 5.5+ switching to RabbitMQ for full on-premise deployments is mandatory. This also means that using the Service Bus Trigger no longer works with Service Bus for Windows Server.

## ​Remote Subprocesses (for pre 5.5 installations)

Because of changes to the message busses used by Frends, Agent groups within an Environment should be reinstalled at the same time. This is required when Remote Subprocesses are being used.

## ​Frends.Tasks.Attributes support to be removed

Frends Tasks Attributes was a way of modifying the Parameter editor for Tasks before Frends 4.5.6, when it was deprecated and support for it was removed in 5.5.3. Previously imported Tasks will continue to work normally, but new Task imports will require migration to System.ComponentModel.Annotation to support conditional parameter displays etc.

[Check here for more information about Custom Tasks](broken://spaces/0p415NUmUmiF4ayjI81L/pages/bzigwi2Gm26t2HlnOmiD).

## SQL Server requirements

The minimum supported version of SQL Server is now MS SQL Server 2017 for on-premise deployments.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.frends.com/release-notes/frends-6.4/breaking-changes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
