This topic describes the problems that you can encounter when you fetch, create, update, and deploy workflows, and when you work with the custom workflow repository, JAR files, and the AI agent. Each section starts with the error, message, or problem that you see, and then explains what it means, why it occurs, and how to fix it.

Workflows are not available

Error: The following message appears:

Workflows need a connected tenant. This workspace was opened from a Git repository, so there is no tenant to deploy to.

What this error means: Workflows need a connection to a tenant.

Why the error occurs: You opened the workspace from a Git repository that holds business configuration. This workspace has no connection to a tenant.

How to fix the issue: Connect the workspace to the tenant, and then fetch the workflows. For the steps, see View the workflows.

Workflows do not load

Error: In the business configuration tree of the Reltio IDE extension view, the Workflows folder does not show Process Definitions or JAR Deployments, and a connection error appears with an Edit Adapter URL button.

What this error means: The integrated development experience cannot reach the Workflow Adapter at the saved URL.

Why the error occurs:

• The saved Workflow Adapter URL is incorrect.
• The host is unreachable, its name does not resolve, or the request timed out.

How to fix the issue:

1. In the error message, select Edit Adapter URL. Alternatively, in the business configuration tree, right-click Workflows, and select Edit Workflow Adapter URL.
2. Enter the correct host for the tenant's environment, without a path. If you do not know the host, ask your Reltio contact.
3. Right-click Workflows, and select Refresh Workflows.

Preventive measures: When the integrated development experience asks you to choose between two Workflow Adapter hosts, confirm the host for your environment with your Reltio contact.

The Workflow Adapter URL is rejected

Error: The following message appears, with the host of the saved Workflow Adapter URL in place of <host>:

Refusing to contact untrusted host "<host>". If this is a sanctioned Reltio environment, add it to the "reltio.trustedHostSuffixes" setting.

What this error means: The host is not in the list of trusted hosts. The integrated development experience does not send your credentials to a host outside this list.

Why the error occurs: The host does not end with a suffix that the reltio.trustedHostSuffixes setting lists. For example, some environments use hosts outside reltio.com.

How to fix the issue:

1. Confirm with your Reltio contact that the host belongs to a Reltio environment.
2. In your user settings, add the suffix of the host to reltio.trustedHostSuffixes. This setting is available only in user settings, not in workspace settings.
3. Fetch the workflows again.

Your session expired or you are not signed in

Error: One of the following appears. In the first message, <environment> stands for the name of your environment:

• The message Session expired for "<environment>". Log in again.
• The message Provide a token for this environment before fetching workflows.
• The text Sign in to continue beside the environment in the business configuration tree.

What this error means: The integrated development experience has no valid session for the environment, so the Workflow Adapter refuses the request (error 401).

Why the error occurs: Your session expired, or you have not signed in to the environment.

How to fix the issue:

1. Sign in to the environment again. For the steps, see Connect to a Reltio tenant.
2. Right-click Workflows, and select Refresh Workflows.

Access is denied

Error: Fetching workflows, deploying a BPMN file, or registering a JAR fails with error 403. For example, a failed deploy shows the following message, with your tenant ID in place of <tenant ID>:

Deploy refused (403). Deploying a workflow requires the ROLE_WORKFLOW_MANAGER role on tenant "<tenant ID>". Your draft is saved and unchanged — ask a tenant admin to grant the role, then deploy again.

What this error means: The Workflow Adapter refused the request for your user.

Why the error occurs: Your Reltio user does not have the role that the action requires on the tenant.

How to fix the issue: Ask the tenant administrator to assign the role that the action requires:

A failed deploy does not change your file.

Requests are rate limited

Error: A message that starts with Rate limited (429) appears when you send requests to the Workflow Adapter, for example when you fetch workflows or deploy a BPMN file.

What this error means: The Workflow Adapter received too many requests in a short time.

How to fix the issue: Wait, and then try again. If the message includes a retry time, wait at least that long.

The deploy fails with error 404

Error: The following message appears when you deploy, with your tenant ID in place of <tenant ID>:

Deploy failed (404). The Workflow Adapter URL saved for "<tenant ID>" may be wrong.

What this error means: The Workflow Adapter at the saved URL did not accept the deploy.

Why the error occurs: The saved Workflow Adapter URL points to the wrong host.

How to fix the issue:

1. In the error message, select Edit Adapter URL. Alternatively, in the business configuration tree, right-click Workflows, and select Edit Workflow Adapter URL.
2. Enter the correct host, and then deploy again.

The deploy is rejected

Error: Deploy to Tenant fails, and the error describes a problem with the BPMN content.

What this error means: The Workflow Adapter cannot accept the BPMN file as written.

Why the error occurs: The BPMN file breaks a structural rule. For example:

• Two elements have the same ID.
• A sequence flow has no source or target, or refers to an element that is not in the file.
• A gateway has no outgoing flow.
• A gateway has one incoming flow and one outgoing flow, so it decides nothing. A gateway that joins several incoming flows into one outgoing flow is valid.

How to fix the issue:

1. In the editor tab of the BPMN file, review the errors in the Problems panel.
2. Fix each error, and then save the file.
3. Deploy the BPMN file again.

Preventive measures: Fix every editor error before you deploy. For the findings, see review the findings.

A message asks what to do with local changes

Message: When you select a workflow under Process Definitions, a message appears, with the process ID of the workflow in place of <process ID>:

"<process ID>" has local changes that have not been deployed.

What this message means: You updated this workflow earlier, and you have not deployed the changes. The changes exist only on your computer.

How to fix the issue: Select one of the following options:

If you select a workflow while a different workflow has local changes, a similar message names the other workflow, and offers the options Review changes, Deploy now, Discard changes, and Keep for now. Keep for now leaves the changes of the other workflow as they are.

Local changes to a deployed workflow are lost

Problem: You updated a deployed workflow, and your changes no longer appear.

What this problem means: The integrated development experience replaced your local changes with the version from the tenant.

Why the problem occurs: You selected Discard Local Changes, or Discard and fetch fresh when you opened the workflow. Local changes exist only on your computer until you deploy them.

How to fix the issue: Make the changes again, and then deploy them. For the steps, see Create or update the BPMN file.

Preventive measures: Before you discard changes, select Compare with Last Fetch to review what you would lose. To work on a variation without changing the deployed workflow, use Duplicate as Draft....

A deployed workflow never runs

Problem: The workflow deploys without an error, but no workflow instances start.

What this problem means: The process is not marked as executable.

Why the problem occurs: The isExecutable attribute of the process is not "true".

How to fix the issue:

1. In the BPMN file, set isExecutable="true" on the process element.
2. Deploy the workflow again.

A workflow instance stops at a gateway

Problem: A workflow instance does not continue past an exclusive gateway, and no error appears.

What this problem means: No outgoing flow from the gateway matched the value, and the gateway has no default flow.

Why the problem occurs: The exclusive gateway has no default flow, and its conditions do not cover every value. A condition value that does not match a choice of the user task exactly, including its capitalization, also matches nothing.

How to fix the issue:

1. Add a default flow to the gateway. Do not add a condition to the default flow.
2. Check that each condition value matches a choice of the user task exactly.
3. Deploy the workflow again. The new version applies to new workflow instances. Workflow instances that are already running continue with the earlier version.

Preventive measures: Review the editor warning for a gateway without a default flow before you deploy.

A user task fails with error code 10044

Error: A workflow instance fails at a user task with error code 10044.

What this error means: The user task is missing a required listener.

Why the error occurs: Each user task needs two create listeners: TaskStartEventListener, and a type listener for the kind of object that the workflow reviews, such as DCRTypeTaskListener, EntityTypeTaskListener, or RelationTypeTaskListener. The workflow deploys without them, but the task fails when it runs.

How to fix the issue:

1. Add the missing listeners to the user task. The editor error names each missing listener.
2. Deploy the workflow again. The new version applies to new workflow instances.

Preventive measures: Start from New Workflow.... The template includes the listeners. Duplicate as Draft... copies only the listeners that the original workflow has.

A workflow with a new process ID does not start

Problem: You deployed a workflow with a new process ID, but actions that started workflows before, such as a data change request, do not start it.

What this problem means: Existing triggers continue to start the workflows that they started before. A deploy with a new process ID adds a separate workflow, and does not replace them.

How to fix the issue:

• To update how an existing workflow runs, deploy your updated BPMN file with the process ID of that workflow. For the steps, see Create or update the BPMN file.
• To run a workflow with a new process ID, start it with the Workflow API.

The diagram is blank in Reltio Console

Problem: The workflow appears as a blank canvas, or with missing steps, in Reltio Console or another BPMN viewer. Show BPMN Diagram in the integrated development experience may still show the workflow.

What this problem means: The diagram section of the BPMN file is missing, incomplete, or refers to a different process ID.

Why the problem occurs: The diagram section was not created, or the process ID changed after the diagram section was created. This often happens when you update a copied BPMN file by hand.

How to fix the issue: Add or correct the diagram section, so that it includes every step and refers to the current process ID. The editor finding names the problem.

Git executable not found

Error: The following message appears when you connect the custom workflow repository:

Git executable not found. Install Git (https://git-scm.com/downloads) and ensure it is on your PATH, then try again.

What this error means: The integrated development experience cannot find Git on your computer.

Why the error occurs: Git is not installed, or its folder is not in the PATH environment variable of your system.

How to fix the issue:

1. Install Git. See Git downloads.
2. In a terminal, run git --version, and confirm that it returns a version.
3. Restart Cursor or VS Code, and then connect the repository again.

The repository URL is rejected

Error: The Connect Custom Workflow Repository box shows one of the following messages, or the connection fails with Unsupported git URL:

• A git URL must not contain credentials.
• A git URL must not contain spaces or control characters.
• Use an https://, ssh://, or git@host:path URL.

What this error means: The URL is not in a form that the integrated development experience accepts.

Why the error occurs: The URL contains a password, contains spaces, or does not use one of the accepted forms.

How to fix the issue: Enter the Git URL of the custom workflow repository without a password, and in one of the accepted forms. For examples, see Connect the custom workflow repository. Git asks you to sign in when it needs credentials.

The Workflows folder already has files from the repository

Error: The following message appears when you connect the custom workflow repository, with the names of the files in place of <files>:

Workflows/ already has files that the repository also contains: <files>. Nothing was changed. Move or rename them, then connect again.

What this error means: The integrated development experience copies the repository into the Workflows folder of the tenant. It does not overwrite files that are already there, so it stops without changing anything.

Why the error occurs: The Workflows folder of the tenant in your workspace contains files with the same names and locations as files in the repository. For example, repository files that had uncommitted changes remain after you select Disconnect Custom Workflow Repository, which keeps them.

How to fix the issue: Move or rename the files that the message lists, and then connect the repository again. Before you remove the files, push any changes that you want to keep.

The connection fails or times out

Error: One of the following messages appears when you connect the custom workflow repository:

• Git operation timed out after 5 minutes. Check your network connection and git credentials, then try again.
• Failed to connect Custom Workflow Repository: followed by the message from Git.

What this error means: Git could not copy the repository.

How to fix the issue:

1. Read the message from Git, if the message includes one.
2. Check your network connection.
3. Check that your Bitbucket account has access to the custom workflow repository, and that the Git URL is correct.
4. Connect the repository again. For the steps, see Connect the custom workflow repository.

No findings appear for a BPMN file in the repository

Problem: The editor reports no findings for a BPMN file in the custom workflow repository, even when the file has errors.

What this problem means: The editor did not check the file.

Why the problem occurs: The editor checks a BPMN file only when its name is <process ID>.bpmn20.xml, where the process ID is valid. A file with another name still appears under Process Definitions, because the business configuration tree lists files by the process ID inside them.

How to fix the issue: Rename the file to <process ID>.bpmn20.xml, using the process ID inside the file. For example, rename a file with the process ID deleteReview to deleteReview.bpmn20.xml. The Show BPMN Diagram and Deploy to Tenant icons in the editor toolbar also appear only for files with this name ending.

A warning remains after you register a JAR

Problem: The editor still shows a warning for each of your own Java classes in the BPMN file, after you register the JAR.

What this problem means: The warning is expected. It does not show that the registration failed.

Why the problem occurs: Reltio does not provide your own Java classes, and the editor does not check which JAR files are registered on the tenant.

How to fix the issue: No fix is needed. To confirm the registration, under JAR Deployments, hover over the JAR, and check its name and description.

A JAR file does not open

Problem: Selecting a JAR under JAR Deployments does not open anything.

What this problem means: This behavior is expected. A JAR file is a compiled package, so the editor does not display its contents.

How to fix the issue: Hover over the JAR to see its name, description, module, and registration details. To review the code, open the Java files under Java Classes and Java Tests.

A JAR is missing from Unregistered

Problem: Reltio notified you that a JAR is ready, but it does not appear under Unregistered, or the Unregistered folder does not appear.

What this problem means: The list of available JAR files was not reloaded, or the JAR is not yet available for the tenant. The Unregistered folder appears only when at least one JAR file is available but not registered.

How to fix the issue:

1. In the business configuration tree, right-click JAR Deployments, and select Refresh JARs. For the registration steps, see Create or update the Java logic.
2. If the JAR still does not appear, contact Reltio Support. Give the module path from the email notification, and ask Reltio Support to register the JAR for the tenant.

The AI agent has no workflow guidance

Problem: The AI agent does not follow the Reltio workflow rules, or reports that a Reltio skill is missing.

What this problem means: The Reltio guidance of the AI agent is missing or out of date in the workspace.

How to fix the issue:

1. Confirm that the reltio.installAgentSkills setting is turned on.
2. Open the Command Palette, and run Reltio: Resync agent assets (skills, Velocity Packs & LCA knowledge base).

Escalate to Reltio Support

If you cannot resolve the problem, contact Reltio Support with the following information:

• The tenant ID and the environment.
• The process ID of the workflow.
• The action that failed, such as Refresh Workflows or Deploy to Tenant.
• The exact text of the message, the editor finding, or the workflow instance error.