Troubleshoot LCA development in integrated development experience
Learn how to resolve common issues when you build, deploy, and register Life Cycle Actions (LCAs) with the AI agent in Reltio’s integrated development experience.
Setup and design issues usually appear in the AI agent's responses. These include missing connections, attributes that do not exist, and hooks that do not apply to the selected object type. These messages are checks by the AI agent, not official Reltio platform error codes.
Runtime issues, such as failures caused by missing attribute values, usually appear in the cloud provider's logs. Compare these logs with Reltio logs to investigate the function's behavior.
No business configuration
Symptom: The AI agent reports that it cannot find a connected tenant or business configuration.
What this error means
The AI agent needs the business configuration to check entity types, relation types, and attributes. Without it, the AI agent cannot check the names in your request or generate an LCA.
Why the error occurs
The integrated development experience is not connected to a tenant or Git repository, or the tenant's configuration was not fetched.
How to fix the issue
Use the method that applies to you:
-
To connect for the first time, in the business configuration tree of the Reltio IDE extension view, select Connect your Reltio Tenant, and then select Add Environment.
-
To add a tenant, in the business configuration tree, right-click the environment, and select Add Tenant.
-
If the tenant is connected but the business configuration tree is empty, select Get Configuration.
-
To work from a Git repository instead, see Connect to a Git repository.
Preventive measures
Follow these practices to avoid this issue.
-
Before you describe an LCA to the AI agent, connect to a Reltio tenant or a Git repository, and fetch the business configuration. When the business configuration is fetched, the business configuration tree lists your entity and relation types.
Name not found
Symptom: The AI agent stops and asks you to confirm an entity type, relation type, attribute, or hook.
What this error means
A name in your request does not exactly match your business configuration, so the AI agent does not guess which one you mean.
Why the error occurs
The name in your request is spelled differently from the configuration, refers to an object that does not exist in the connected configuration, or names a hook that does not apply to the type.
How to fix the issue
Use the following steps to resolve the issue.
-
Review the close matches that the AI agent suggests, and reply with the exact name.
-
To find the exact name, check the business configuration tree.
-
If the hook does not apply to the type, ask the AI agent which hooks apply, and choose one.
Preventive measures
Follow these practices to avoid this issue.
-
Use the names exactly as they appear in the business configuration tree.
Build fails
Symptom: The Maven build fails for the generated LCA project.
What this error means
Maven cannot complete mvn clean package for the generated LCA project, or the AI agent reports that Maven setup is incomplete.
Why the error occurs
The local settings.xml file is missing the Reltio repository credentials, the credentials are incorrect, or a generated unit test fails.
How to fix the issue
Use the following steps to resolve the issue.
-
Add or update the
reltio-libs-publicserver entry insettings.xmlas described in Configure LCA development. -
Request read-only Maven credentials from Reltio Support or your Reltio contact if you do not have them.
-
If a unit test fails, share the Maven error with the AI agent in a prompt. The AI agent can update the generated code or tests. Then run
mvn clean packageagain.
Preventive measures
Follow these practices to avoid this issue.
-
Complete Maven setup on each developer machine before the first build.
-
Use the
com.reltio:life-cycle-frameworkversion that matches the latest Reltio release. Older pinned versions may fail to build as the public repository evolves.
Deploy fails
Symptom: The AI agent cannot deploy the function, or the cloud provider reports a deployment failure.
What this error means
The AI agent cannot deploy the built artifact to AWS Lambda, Google Cloud Functions, or Azure Functions, or deployment fails in the cloud provider.
Why the error occurs and how to fix it
Deployment can fail for the following causes:
| Cause | Fix |
|---|---|
| The project has not been built. The AI agent reports: "Build it, then run the deploy command again." | From the project folder, run mvn clean package, then ask the AI agent to deploy again. |
.env does not exist. | In the project folder, copy .env.example to .env, and enter a value for each variable. |
.env is missing required variables. | Enter the variables that the AI agent reports as missing. For the full list, see Configure LCA development. |
| Cloud credentials have expired. | Get new credentials for your cloud account, and update .env. |
| Cloud credentials were rejected. | Check that the credentials in .env are correct and belong to the target cloud account. |
| The cloud account is missing a permission. The cloud provider returns a 403 error. | Ask your cloud administrator to grant the permission named in the error. |
The AWS CLI, the Google Cloud CLI (gcloud), or the Azure CLI (az) is not installed or cannot be found. | Install the command-line tool for your cloud. In a terminal, run aws --version, gcloud --version, or az --version to confirm that it works. Restart Cursor or VS Code so it picks up the change, then deploy again. |
Do not enter credential values in prompts to the AI agent or commit .env to source control.
Preventive measures
Follow these practices to avoid this issue.
-
Build the project before you deploy it.
-
Before you deploy, check that the cloud credentials in
.envare current.
Action never runs
Symptom: The LCA does not run when you save or update a record.
What this error means
The LCA does not run when you save or update a record or perform an operation that should trigger the lifecycle hook.
Why the error occurs
The hook name or object type in business configuration may be incorrect, the configuration may not have been applied to the tenant, or Reltio-to-cloud connectivity may be incomplete.
How to fix the issue
Use the following steps to resolve the issue.
-
Verify the exact hook name and the entity or relation type against your business configuration in
L3.reltio.jsonorBusinessConfig.json. -
In Reltio Console, go to and confirm the connection for your cloud provider is configured, as described in Configure LCA development.
-
Confirm the change was published. For a tenant connection, select Apply Configuration to Tenant in the business configuration tree. For a Git repository, commit and push the updated file. For more information, see Create and deploy an LCA.
-
Check the cloud provider function logs to confirm whether Reltio invoked the function.
Preventive measures
Follow these practices to avoid this issue.
-
Review the proposed configuration changes before you apply updates to
lifecycleActions. -
If the AI agent's deployment summary includes Reltio Console setup steps, complete them before you test the LCA.
-
After applying updates, retrieve the latest configuration from the tenant or Git repository and confirm that the business configuration tree reflects the configuration applied to the tenant.
Changes do not save
Symptom: The LCA runs, but the expected attribute changes do not appear on the record.
What this error means
The LCA runs, but attribute changes you expect from the hook do not persist on the record.
Why the error occurs
The hook handler does not return the updated object to the platform.
How to fix the issue
Use the following steps to resolve the issue.
-
Update the hook implementation so it returns the modified object required for that hook type. You can ask the AI agent to make this change.
-
Rebuild and redeploy the function, then test again with a sample record.
Preventive measures
Follow these practices to avoid this issue.
-
Test the deployed function with a sample payload and review cloud logs before you apply tenant configuration changes.
Errors on some records
Symptom: The LCA succeeds for some records and fails for others that use the same hook.
What this error means
The LCA succeeds for some records and fails for others that use the same hook.
Why the error occurs
The code uses attribute values that are empty or missing on some records without checking first.
How to fix the issue
Use the following steps to resolve the issue.
-
Add checks for missing or empty attribute values before the code reads or modifies them. You can ask the AI agent to make this change.
-
Rebuild, redeploy, and retest with records that previously failed.
Preventive measures
Follow these practices to avoid this issue.
-
Ask the AI agent to include checks for missing attribute values in the generated code.
Slow response
Symptom: Save or update operations take noticeably longer when the lifecycle hook runs.
What this error means
Save or update operations take noticeably longer when the lifecycle hook runs.
Why the error occurs
The hook performs heavy work or calls external systems synchronously during the lifecycle event.
How to fix the issue
Use the following steps to resolve the issue.
-
Reduce work inside the hook. Keep logic lightweight for the lifecycle path.
-
Move non-essential processing out of the synchronous hook where your design allows.
Preventive measures
Follow these practices to avoid this issue.
-
Before you approve deployment, review the generated code for external calls and long-running steps.
Escalate to Reltio Support
If you cannot resolve the issue using the sections above, contact Reltio Support with the following information:
-
Your exact prompts and the AI agent's responses
-
Your tenant ID
-
The integrated development experience version, shown in the Extensions view of Cursor or VS Code
-
The cloud provider and region
-
The function name
-
The hook and the entity or relation type involved
-
The exact error text from the AI agent, Maven, the cloud provider, or Reltio logs